Design model

Platform spec article

Design model

Back to pckg client contract ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-hub-authority Hub authority Accepted

   Hub authority

   Context

   One client story.

   Decision

   Hub owns HTTP and auth.

   Consequences

   Extension defers.

   Verification anchors

   beskid_pckg; pckgClient.

   Open full ADR page

2. 0002-registry-assigned-versions Registry versions Accepted

   Registry versions

   Context

   Manual semver drift.

   Decision

   Registry-assigned publish versions in routine flows.

   Consequences

   UI shows server version.

   Verification anchors

   publish API tests.

   Open full ADR page

Articles

• Contracts and edge cases Registry client guarantees and failure modes. article Standard
• Design model Conceptual model for the Beskid pckg registry client (`beskid_pckg`). article Standard
• Examples Example `beskid pckg` invocations and configuration. article Standard
• FAQ and troubleshooting Common pckg client and registry issues. article Standard
• Flow and algorithm Pack, upload, and query flows for the pckg registry client. article Standard
• Verification and traceability Tests and traceability for the pckg client contract. article Standard

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  Registry client

  Parent area

• Feature
  pckg client contract

  Parent feature hub

• Feature
  Workspace and lock contracts

  Fetch materializes roots referenced by locks

Purpose

beskid_pckg is the single HTTP client for the pckg registry service. The CLI exposes it as beskid pckg <subcommand>; analysis-time fetch uses the same PckgClient types. Server behavior for published artifacts is implemented in pckg/src/Server/ (validation, docs ingestion, workspace bundles).

Component model

flowchart LR
  CLI[beskid pckg CLI]
  Client[PckgClient]
  CFG[PckgClientConfig]
  HTTP[reqwest]
  SVC[pckg Server API]
  CLI --> Client
  CFG --> Client
  Client --> HTTP --> SVC

Piece	Role
PckgClientConfig	base_url, timeout, user_agent, auth (BearerToken or PublisherApiKey)
PckgClient	JSON and multipart request builders with unified PckgError mapping
pack module	Walk tree → zip .bpk, inject README.md, build package.json (PackProfile)
Repository config	.beskid/pckg/repositories.json maps registry aliases to API keys

Authentication

Authenticated routes must receive either:

• BESKID_PCKG_TOKEN / --bearer-token, or
• BESKID_PCKG_API_KEY / --api-key (header name from config, used for publisher keys)

Missing auth on require_auth endpoints returns PckgError::MissingAuthToken without contacting the network.

Pack profiles

Profile	Detection	package.json
Library	Default or non-Template Project.proj	Includes docs paths, api.json when present under .beskid/docs/
Template	project.type = Template	packageKind: template + summary from .beskid/template.json

Readme resolution uses discover_readme_for_package_root from beskid_analysis (optional readme key or default readme.md).

Server-side counterparts

Concern	pckg path
Publish validation	pckg/src/Server/Services/PackageArtifactValidator.cs
Docs + api.json	pckg/src/Server/Services/PackagePublishDocumentation.cs
Workspace bundles	pckg/src/Server/Services/Workspace/WorkspacePublishService.cs
Dashboard listing	pckg/src/Server/Components/Pages/Dashboard/Packages.razor.cs

Implementation anchors

• compiler/crates/beskid_pckg/src/lib.rs, client.rs, cli.rs, pack.rs
• Models: compiler/crates/beskid_pckg/src/models.rs, packages.rs