Protocol support
Écluse renders this page from the OpenAPI document it publishes as JSON, so the page and the document always agree. The reference below lists every endpoint an Écluse server answers, with the responses each one returns.
Which registry protocols this Écluse server speaks, and exactly what is and is not supported, per ecosystem. An OpenAPI spec for operators and contributors -- not a client-integration contract: registry clients hardcode the protocol and never read this document. Generated statically from the closed serve-route enumeration; it is not served.
API version: 0.1.0
Servers
| URL | Description |
|---|---|
https://registry.ecluse.example | The proxy's externally-reachable base URL; served artifact URLs resolve against it. |
Endpoints
GET /npm/-/ping
Liveness probe
Answered locally with 200 and an empty object; npm ping checks the endpoint it talks to is up, so there is no reason to round-trip upstream.
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
200 | An empty object. | application/json | any |
HEAD /npm/-/ping
Liveness probe
Answered locally with 200 and an empty object; npm ping checks the endpoint it talks to is up, so there is no reason to round-trip upstream.
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
200 | An empty object. | - | - |
GET /npm/-/v1/search
Package search (not supported)
Search is a first-class documented boundary: a discovery convenience, not an install path, so Écluse returns 501 and points to the public registry's website.
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
501 | Not implemented: search is not supported. | application/json | object |
HEAD /npm/-/v1/search
Package search (not supported)
Search is a first-class documented boundary: a discovery convenience, not an install path, so Écluse returns 501 and points to the public registry's website.
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
501 | Not implemented: search is not supported. | - | - |
GET /npm/{package}
Fetch a package's metadata (packument)
Returns Écluse's merged-and-filtered packument: versions merged across upstreams and gated, each dist.tarball rewritten to resolve back through this proxy. With no surviving version the status follows the most recoverable cause.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
package | path | yes | string | The package name, URL-encoded; a scoped name is @scope%2Fname. |
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
200 | The synthesized packument. | application/json | SynthesizedPackument |
304 | The client's validator matched the synthesized packument. | - | - |
401 | Edge authentication failed. | application/json | object |
403 | Every version was withheld by policy or admission, and none survived the merge. | application/json | object |
500 | A permanent or internal inability to decide. | application/json | object |
502 | A responding upstream returned a packument for a different package. | application/json | object |
503 | A transient upstream or advisory condition; retry (see Retry-After). | application/json | object |
PUT /npm/{package}
Publish a first-party package
Relays the publish document to the configured publication target after the anti-shadowing scope guard. Écluse keys the write on the route's package name, never the document's self-reported name. The target's status and JSON-labelled bytes are relayed transparently.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
package | path | yes | string | The package name, URL-encoded; a scoped name is @scope%2Fname. |
Request body (required)
The npm publish document (the version manifest plus the base64-encoded tarball in _attachments).
| Media type | Schema |
|---|---|
application/json | PublishDocument |
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
default | The publication target's status and JSON-labelled response bytes are relayed. Local authentication, scope, configuration, transport, and internal failures use npm's JSON error body. | application/json | string (binary) |
HEAD /npm/{package}
Fetch a package's metadata (packument)
Returns Écluse's merged-and-filtered packument: versions merged across upstreams and gated, each dist.tarball rewritten to resolve back through this proxy. With no surviving version the status follows the most recoverable cause.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
package | path | yes | string | The package name, URL-encoded; a scoped name is @scope%2Fname. |
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
200 | The synthesized packument. | - | - |
304 | The client's validator matched the synthesized packument. | - | - |
401 | Edge authentication failed. | - | - |
403 | Every version was withheld by policy or admission, and none survived the merge. | - | - |
500 | A permanent or internal inability to decide. | - | - |
502 | A responding upstream returned a packument for a different package. | - | - |
503 | A transient upstream or advisory condition; retry (see Retry-After). | - | - |
GET /npm/{package}/-/{filename}
Stream a package artifact (tarball)
The artifact bytes are streamed verbatim with bounded memory; the client verifies the bytes against the packument's preserved integrity digest. Upstream statuses, headers, and media types are relayed transparently; locally generated refusals use npm's JSON error shape.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
package | path | yes | string | The package name, URL-encoded; a scoped name is @scope%2Fname. |
filename | path | yes | string | The artifact's on-the-wire file name, e.g. lodash-4.17.21.tgz. |
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
default | An upstream-controlled artifact response is relayed transparently. Local authentication, policy, availability, and internal failures use npm's JSON error body under their corresponding status. | */* | string (binary) |
HEAD /npm/{package}/-/{filename}
Stream a package artifact (tarball)
The artifact bytes are streamed verbatim with bounded memory; the client verifies the bytes against the packument's preserved integrity digest. Upstream statuses, headers, and media types are relayed transparently; locally generated refusals use npm's JSON error shape.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
package | path | yes | string | The package name, URL-encoded; a scoped name is @scope%2Fname. |
filename | path | yes | string | The artifact's on-the-wire file name, e.g. lodash-4.17.21.tgz. |
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
default | An upstream-controlled artifact response is relayed transparently. Local authentication, policy, availability, and internal failures use npm's JSON error body under their corresponding status. | - | - |
GET /npm/{unsupportedPath}
Deny by default (unsupported path)
Any request under this mount matched by none of the routes above is denied with 404 -- deny by default at the routing layer.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
unsupportedPath | path | yes | string | Any path under this mount matched by none of the routes above. |
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
404 | Unrecognised path; deny by default. | application/json | object |
HEAD /npm/{unsupportedPath}
Deny by default (unsupported path)
Any HEAD request under this mount matched by none of the routes above is denied with 404 and no response body.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
unsupportedPath | path | yes | string | Any path under this mount matched by none of the routes above. |
Responses
| Status | Description | Media type | Schema |
|---|---|---|---|
404 | Unrecognised path; deny by default. | - | - |
Schemas
PublishDocument
The npm publish document, relayed to the publication target (its full shape is npm's, not re-specified here).
Additional properties: yes
SynthesizedPackument
Écluse's merged-and-filtered view of a package's metadata. Versions are merged across upstreams and gated (private versions trusted, public versions admitted only by policy), and each version's dist.tarball is rewritten to resolve back through this proxy. Only the fields Écluse reads and transforms are modelled; every other field is relayed unchanged from the contributing upstream (the private upstream wins on a collision).
| Property | Type | Required | Description |
|---|---|---|---|
dist-tags | object | no | Tag to version string. latest is repointed to the newest surviving version after the gate. |
name | string | yes | The package name. |
time | object | no | Publish timestamps: created, modified, and one entry per version. |
versions | object | yes | Surviving versions, keyed by version string. |
Additional properties: yes
The raw OpenAPI document is published at /api/openapi.json.