llard Service Specification

llard Service Specification

1. Scope

This document specifies the externally observable contract of the llard HTTP service: its request/response format and the guarantees a client may rely on. It does not describe internal mechanisms.

2. Endpoint

GET /v1/artifacts/<module>@<version>?<matrix query>

Path

• <module> — package module identifier (e.g. madler/zlib).
• <version> — version string (e.g. v1.3.1).

Query

• A flat set of key=value pairs, in the natural shape of the LLAR matrix CLI (e.g. arch=amd64&os=linux&debug=false).
• The query string is not a serialized formula.Matrix and does not expose Require or Options.
• The mapping from query values to LLAR's internal matrix representation is owned by the LLAR build path and is not part of this wire protocol.

Artifact Key

artifactKey = module + version + matrixStr

• matrixStr is the canonical LLAR matrix string for the selected values.
• Query parameter order MUST NOT affect artifactKey.

3. Response Format

• Content type: application/x-cmdjsonl. See github.com/qiniu/x/cmdjsonl for the line format (Command <space> JSON object, newline-delimited).
• The response body is a stream of command lines, terminating in exactly one of:
  • a completion command line carrying artifact metadata (download location, archive type, LLAR metadata, checksum), or
  • an error command line describing the failure.
• Command lines are delivered incrementally as build progress occurs, not buffered until completion.

4. Request Semantics

4.1 One root per request

Each request corresponds to exactly one requested root artifact (module@version + matrix). It does not separately address dependency artifacts.

4.2 Idempotent outcome

A request for a given artifactKey always terminates in the same completion artifact, regardless of:

• whether that artifact already existed before the request was made;
• whether the artifact was produced by this request, by a concurrent request, or by a prior request.

4.3 Cache-miss builds resolve dependencies

When a request requires a build (no existing artifact for artifactKey), the build resolves the full dependency graph for the requested module/version/matrix and may, as part of producing the root artifact, also cause artifacts for dependencies to become available for future requests addressing those dependencies' own artifactKeys.

5. Error Semantics

Condition	Response
<module>@<version> cannot be resolved	Error command line; no artifact is produced for artifactKey
Build failure (root or any dependency required by the root build)	Error command line; no completion artifact is produced for the root's artifactKey

A request that ends in an error command line has no side effect observable to subsequent requests for the same artifactKey (i.e. it does not "poison" the key — a later request may succeed).

6. Out of Scope

• llar install client behavior (download, checksum verification, .cache.json and install directory layout).
• Internal representation of formula.Matrix and the query-to-matrix mapping algorithm.
• cmdjsonl line format details — see github.com/qiniu/x/cmdjsonl.
• Caching, routing, storage, and coordination mechanisms.