# Monitors & Federation API Proposal

*For Monitors & Registries:*

### `Warg-Registry` HTTP Header
For all API endpoints, if the `Warg-Registry` header is present in the request, the response will be as if the registry at the domain name specified in the header value was the one responding.

The response will include the same `Warg-Registry` header and value if the server is responding as that registry. If the response header is omitted, the client should assume that the server ignored the request header.

### `POST /v1/verify/checkpoint`
Request body is the signed timestamped checkpoint envelope to be verified. The `Warg-Registry` specifies the domain name of the registry checkpoint that is being verified. Response is success status code or error status code with an error messsage.

**Example:**
Request Header `Warg-Registry: registry.example.com`
`POST` Body:

{
  "contents": {
    "logLength": 42,
    "logRoot": "sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c",
    "mapRoot": "sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c",
    "timestamp": 1692035502
  },
  "keyId": "sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c",
  "signature": "ecdsa-p256:MEUCIQCzWZBW6ux9LecP66Y+hjmLZTP/hZVz7puzlPTXcRT2wwIgQZO7nxP0nugtw18MwHZ26ROFWcJmgCtKOguK031Y1D0="
}

*For Registries:*

### `GET /v1/ledger`
Response is a JSON:

{
  "hashAlgorithm": "sha256",
  "sources": [
    {
      "firstRegistryIndex": 0,
      "lastRegistryIndex": 99999,
      "url": "https://someurl.com/file-1",
      "acceptRanges": true,
      "contentType": "application/vnd.bytecodealliance.registry.ledger.packed"
    },
    {
      "firstRegistryIndex": 100000,
      "lastRegistryIndex": 149999,
      "url": "https://someurl.com/file-2",
      "acceptRanges": true,
      "contentType": "application/vnd.bytecodealliance.registry.ledger.packed"
    }
  ]
}

Each source is an HTTP `GET` that returns a binary file with `Vec<(LogId, RecordId)>` with both `LogId` and `RecordId` serialized according to the binary representation of the `hashAlgorithm` and the length of the `Vec` in the file equal to (`lastRegistryIndex - firstRegistryIndex + 1`). The `firstRegistryIndex` and `lastRegistryIndex` are inclusive ranges.

In the case of the example, this would be a repeating sequence of 64 bytes (32 bytes for each the `LogId` and `RecordId`). The sources array and the `url` data is in ascending order without gaps. `acceptRanges` field is optional for accepting HTTP `Range` header.

### `GET /v1/namespace/imports`
Response is a JSON:

    {
        "{namespace}": {
            "namespace": "{source-registry-namespace}",
            "registry": "{registry-domain-name}",
            "direct": true
        }
    }

For each imported namespace, there is an object key that is the imported `namespace` name with an object that specifies the source registry's `namespace` (omitted, if imported as the same name) and the `registry` domain name.

During package publishing, the registry will validate package imports against what is available in its own registry and these provided imported namespaces from other registries.

If the registry does not support using the `Warg-Registry` subject header for specified registry domain name, the `direct` field is set to `true`.

### `POST /v1/package/{logId}/record` (Modify Current Endpoint)
Extend the current ***publish package record*** endpoint with an optional field `namespaceImports` in the request body.

When publishing a package with an import of another registry with a namespace not currently present in the registry namespace imports, the client will include the `namespaceImports` as part of the publish request.

For each missing imported namespace, there is an object key that is the imported `namespace` name with an object that specifies the source registry's `namespace` (omitted, if imported as the same name) and the `registry` domain name.

The registry server can choose to adopt policies on whether to accept the publish or reject. If a registry does not allow importing new namespaces through this API, it will always reject publishes with unknown imports.

After publishing, the newly imported namespaces are expected to be present in the `GET /v1/namespace/imports` endpoint.

Example:

{
  "packageId": "fun-corp:most-fun-pkg",
  "record": {
    "contentBytes": "ZXhhbXBsZQ==",
    "keyId": "sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c",
    "signature": "ecdsa-p256:MEUCIQCzWZBW6ux9LecP66Y+hjmLZTP/hZVz7puzlPTXcRT2wwIgQZO7nxP0nugtw18MwHZ26ROFWcJmgCtKOguK031Y1D0="
  },
  "namespaceImports": {
     "wasi": {
         "registry": "registry.wasi.dev"
     },
     "ba": {
         "registry": "registry.bytecodealliance.org",
         "namespace": "bytecode-alliance"
     }
  }
}