Node protocol

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Node-to-node enrollment, socket, artifacts and uploads; each route checks its own credential.

Back to the web API reference.

POST /api/node/v1/enroll

POST /api/node/v1/enroll: redeem an enrollment link. Answers {library_id, node_id}; 403 transport_insecure when the connection fails the transport policy, 403 enrollment_refused for any link that does not redeem.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Request body

application/json: EnrollBody

  • link_idstringrequiredLink id from the token.
  • secretstringrequiredLink secret from the token.
  • sign_pkstringrequiredEd25519 public signing key.
  • box_pkstringrequiredX25519 public box key.
  • software_versionstringHost's Bookclerk version.

Responses

  • 200The host is enrolled; its node credential. Body: EnrolledNodeView (application/json)2 fields
    • library_idstringrequiredThe library the node joined.
    • node_idstringrequiredThe node id minted for it.
  • 400The body is not an enroll request, or its keys are not base64url. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 403The connection failed the transport policy (transport_insecure, with the check in reason), or the link does not redeem: unknown, used, expired, revoked, or enrollment is off (enrollment_refused). A write sent with a session cookie but without a matching Origin or Referer is refused. Body: NodeRefusal (application/json)
  • 404The node API is not mounted on this listener (node_api_unmounted). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 413The body is larger than 16 KiB. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 415The request is not application/json. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503The enrollment could not be read or recorded; try again (enrollment_unavailable). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/node/v1/enroll' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"link_id": "9f2c7b1e4a8d3c6f0b5e2a7d4c1f8e3b", "secret": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/enroll' `
    -Method Post `
    -ContentType 'application/json' `
    -Body '{"link_id": "9f2c7b1e4a8d3c6f0b5e2a7d4c1f8e3b", "secret": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/node/v1/enroll",
    json={"link_id": "9f2c7b1e4a8d3c6f0b5e2a7d4c1f8e3b", "secret": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/enroll", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"link_id": "9f2c7b1e4a8d3c6f0b5e2a7d4c1f8e3b", "secret": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/node/v1/enroll")
    .json(&serde_json::json!({"link_id": "9f2c7b1e4a8d3c6f0b5e2a7d4c1f8e3b", "secret": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The host is enrolled; its node credential.

{
  "library_id": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "node_id": "7d2b9e4c-1f3a-4b8d-9c6e-2a5f8b1d4e7c"
}

Schema:

{
  "type": "object",
  "description": "JSON body after an enrollment link or branch sign-in was redeemed.",
  "required": [
    "library_id",
    "node_id"
  ],
  "properties": {
    "library_id": {
      "type": "string",
      "description": "The library the node joined.",
      "example": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
    },
    "node_id": {
      "type": "string",
      "description": "The node id minted for it.",
      "example": "7d2b9e4c-1f3a-4b8d-9c6e-2a5f8b1d4e7c"
    }
  }
}

Status 400: The body is not an enroll request, or its keys are not base64url.

{
  "error": "sign_pk and box_pk must be base64url"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 403: The connection failed the transport policy (transport_insecure, with the check in reason), or the link does not redeem: unknown, used, expired, revoked, or enrollment is off (enrollment_refused). A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "enrollment_refused"
}

Schema:

{
  "anyOf": [
    {
      "type": "object",
      "description": "The connection failed the transport policy.",
      "required": [
        "error",
        "reason"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Always `transport_insecure`.",
          "example": "transport_insecure"
        },
        "reason": {
          "type": "string",
          "description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
          "example": "plain_http"
        }
      }
    },
    {
      "type": "object",
      "description": "The session middleware's standard body (`error`, `message`, `status`).",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    },
    {
      "type": "object",
      "description": "The handler refused with a slug in `error`.",
      "required": [
        "error"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "What went wrong, as the handler describes it.",
          "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
        }
      }
    },
    {
      "type": "object",
      "description": "The handler refused with a slug in `error` and a sentence in `detail`.",
      "required": [
        "error",
        "detail"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Stable machine slug clients branch on.",
          "example": "invalid_request"
        },
        "detail": {
          "type": "string",
          "description": "What went wrong, for the person reading the answer.",
          "example": "the redirect URI must be loopback or https"
        }
      }
    }
  ],
  "description": "A `403` from a node API route: the transport policy's refusal, the standard body, or the handler's own error; the route's examples name each."
}

Status 404: The node API is not mounted on this listener (node_api_unmounted).

{
  "error": "node_api_unmounted"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 413: The body is larger than 16 KiB.

{
  "error": "request too large"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 415: The request is not application/json.

{
  "error": "expected application/json"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 503: The enrollment could not be read or recorded; try again (enrollment_unavailable).

{
  "error": "enrollment_unavailable"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/node/v1/info

GET /api/node/v1/info.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Responses

  • 200What this library says about itself to a joining install. Body: OwnerInfo (application/json)8 fields
    • library_idstringrequiredThe library id.
    • library_namestringrequiredA name to show for the library.
    • originstringrequiredThe library's canonical origin: the one the node handshake signs and the authorize endpoint lives under.
    • transportstringrequiredThe node API transport mode (acme, proxy, self_signed, loopback).
    • enrollmentbooleanrequiredWhether the library lets new branches join (core.branch_enrollment).
    • spki_fingerprintstring or nullIn self_signed mode: base64url SHA-256 of the certificate's SubjectPublicKeyInfo, which the joining operator confirms against the owner's Settings → Branches page.
    • software_versionstringThe library's Bookclerk version.
    • ancestryarray of stringThe library's ancestry: its own library id first, then the library id of every library above it up to the root. A joining library refuses a parent whose ancestry names its own library id, so a tree of libraries never becomes a cycle.
  • 403The connection failed the transport policy (transport_insecure, with the check in reason). Body: TransportRefused (application/json)2 fields
    • errorstringrequiredAlways transport_insecure.
    • reasonstringrequiredThe transport check that refused the connection (plain_http, unknown_peer, untrusted_forwarding, proxy_proto_missing, proxy_proto_ambiguous, proxy_proto_not_https, public_origin_not_https, listener_mode_mismatch, node_api_misconfigured).
  • 404The node API is not mounted on this listener (node_api_unmounted). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503This library's identity row (library_unavailable) or origin (origin_unavailable) is not available yet. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/node/v1/info'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/info'
import requests

response = requests.get("http://127.0.0.1:8787/api/node/v1/info")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/info");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/node/v1/info").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: What this library says about itself to a joining install.

{
  "library_id": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "library_name": "books.example.com",
  "origin": "https://books.example.com",
  "transport": "acme",
  "enrollment": true,
  "spki_fingerprint": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o",
  "software_version": "0.4.0",
  "ancestry": [
    "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
  ]
}

Schema:

{
  "type": "object",
  "description": "`GET /api/node/v1/info` answer.",
  "required": [
    "library_id",
    "library_name",
    "origin",
    "transport",
    "enrollment"
  ],
  "properties": {
    "library_id": {
      "type": "string",
      "description": "The library id.",
      "example": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
    },
    "library_name": {
      "type": "string",
      "description": "A name to show for the library.",
      "example": "books.example.com"
    },
    "origin": {
      "type": "string",
      "description": "The library's canonical origin: the one the node handshake signs and\nthe authorize endpoint lives under.",
      "example": "https://books.example.com"
    },
    "transport": {
      "type": "string",
      "description": "The node API transport mode (`acme`, `proxy`, `self_signed`,\n`loopback`).",
      "example": "acme"
    },
    "enrollment": {
      "type": "boolean",
      "description": "Whether the library lets new branches join (`core.branch_enrollment`).",
      "example": true
    },
    "spki_fingerprint": {
      "type": [
        "string",
        "null"
      ],
      "description": "In `self_signed` mode: base64url SHA-256 of the certificate's\nSubjectPublicKeyInfo, which the joining operator confirms against\nthe owner's Settings → Branches page.",
      "example": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o"
    },
    "software_version": {
      "type": "string",
      "description": "The library's Bookclerk version.",
      "example": "0.4.0"
    },
    "ancestry": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The library's ancestry: its own library id first, then the library\nid of every library above it up to the root. A joining library\nrefuses a parent whose ancestry names its own library id, so a\ntree of libraries never becomes a cycle.",
      "example": [
        "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
      ]
    }
  }
}

Status 403: The connection failed the transport policy (transport_insecure, with the check in reason).

{
  "error": "transport_insecure",
  "reason": "plain_http"
}

Schema:

{
  "type": "object",
  "description": "JSON body of a `403` from the node API's transport policy: the\nconnection is plain HTTP off loopback, or arrived through a proxy the\npolicy does not trust, and `reason` names the check that refused it.",
  "required": [
    "error",
    "reason"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Always `transport_insecure`.",
      "example": "transport_insecure"
    },
    "reason": {
      "type": "string",
      "description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
      "example": "plain_http"
    }
  }
}

Status 404: The node API is not mounted on this listener (node_api_unmounted).

{
  "error": "node_api_unmounted"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 503: This library's identity row (library_unavailable) or origin (origin_unavailable) is not available yet.

{
  "error": "library_unavailable"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/node/v1/enroll/oauth

POST /api/node/v1/enroll/oauth: redeem an approved branch sign-in. Answers {library_id, node_id} for a branch, plus connection and the sealed bootstrap for a shared branch; 403 transport_insecure for a refused connection, 403 enrollment_refused for a code that does not redeem (unknown, used, expired, another client's, a wrong verifier or redirect URI, enrollment off, or the user no longer active).

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Request body

application/json: OAuthEnrollRequest

  • codestringrequiredThe authorization code from the callback.
  • code_verifierstringrequiredThe PKCE verifier.
  • redirect_uristringrequiredThe redirect URI the authorization was requested with.
  • sign_pkstringrequiredEd25519 public signing key.
  • box_pkstringrequiredX25519 public box key.
  • branch_namestringThe name this branch joins as (the node's label).
  • software_versionstringThe joining install's Bookclerk version.
  • connectionConnectionTypeThe connection type the code was approved for. It must match the one bound to the code at consent; left out for a branch.

Responses

  • 200The install is enrolled: its library and node ids for a branch, and for a shared branch join also connection and the bootstrap sealed to its box key. Body: OAuthEnrollAnswer (application/json)5 fields
    • library_idstringrequiredThe library id.
    • node_idstringrequiredThe node id recorded for the joining install.
    • connectionConnectionTypeThe connection type recorded (branch when left out).
    • bootstrapstring or nullFor a shared branch: the [crate::SharedBranchBootstrap] sealed to the node's box key ([crate::seal_shared_branch_bootstrap]), as base64url without padding.
    • accountsstring or nullFor a branch whose user chose "Bring my store connections to this branch": the user's own store accounts as a [crate::AccountBundle] sealed to the node's box key ([crate::seal_account_bundle]), as base64url without padding. Left out when the user did not choose it or had none to bring.
  • 400The body is not an enroll request, or its keys are not base64url. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 403The connection failed the transport policy (transport_insecure, with the check in reason), or the code does not redeem: blank, unknown, used, expired, wrong verifier, or the user may no longer let a shared branch join (enrollment_refused). A write sent with a session cookie but without a matching Origin or Referer is refused. Body: NodeRefusal (application/json)
  • 404The node API is not mounted on this listener (node_api_unmounted). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409This library's database cannot be shared with another server (database_not_shareable). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 413The body is larger than 16 KiB. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 415The request is not application/json. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503The enrollment could not be read or recorded; try again (enrollment_unavailable). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/node/v1/enroll/oauth' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"code": "BhD5jGe21A8WEIm7SrdBZ-KXhs5B9HkeUSEc58grX94", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/enroll/oauth' `
    -Method Post `
    -ContentType 'application/json' `
    -Body '{"code": "BhD5jGe21A8WEIm7SrdBZ-KXhs5B9HkeUSEc58grX94", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/node/v1/enroll/oauth",
    json={"code": "BhD5jGe21A8WEIm7SrdBZ-KXhs5B9HkeUSEc58grX94", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/enroll/oauth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"code": "BhD5jGe21A8WEIm7SrdBZ-KXhs5B9HkeUSEc58grX94", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/node/v1/enroll/oauth")
    .json(&serde_json::json!({"code": "BhD5jGe21A8WEIm7SrdBZ-KXhs5B9HkeUSEc58grX94", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The install is enrolled: its library and node ids for a branch, and for a shared branch join also connection and the bootstrap sealed to its box key.

{
  "library_id": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "node_id": "7d2b9e4c-1f3a-4b8d-9c6e-2a5f8b1d4e7c"
}

Schema:

{
  "type": "object",
  "description": "`POST /api/node/v1/enroll/oauth` answer.",
  "required": [
    "library_id",
    "node_id"
  ],
  "properties": {
    "library_id": {
      "type": "string",
      "description": "The library id.",
      "example": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
    },
    "node_id": {
      "type": "string",
      "description": "The node id recorded for the joining install.",
      "example": "7d2b9e4c-1f3a-4b8d-9c6e-2a5f8b1d4e7c"
    },
    "connection": {
      "type": "string",
      "description": "The connection type recorded (`branch` when left out).",
      "enum": [
        "branch",
        "shared_branch"
      ]
    },
    "bootstrap": {
      "type": [
        "string",
        "null"
      ],
      "description": "For a shared branch: the [`crate::SharedBranchBootstrap`] sealed to the node's box\nkey ([`crate::seal_shared_branch_bootstrap`]), as base64url without padding.",
      "example": "Qm9va2NsZXJrIHNlYWxlZCBjbGVyayBib290c3RyYXA6IGVwaGVtZXJhbCBrZXkgKyBjaXBoZXJ0ZXh0"
    },
    "accounts": {
      "type": [
        "string",
        "null"
      ],
      "description": "For a branch whose user chose \"Bring my store connections to this\nbranch\": the user's own store accounts as a\n[`crate::AccountBundle`] sealed to the node's box key\n([`crate::seal_account_bundle`]), as base64url without padding.\nLeft out when the user did not choose it or had none to bring.",
      "example": "Qm9va2NsZXJrIHNlYWxlZCBhY2NvdW50IGJ1bmRsZTogZXBoZW1lcmFsIGtleSArIGNpcGhlcnRleHQ"
    }
  }
}

Status 400: The body is not an enroll request, or its keys are not base64url.

{
  "error": "sign_pk and box_pk must be base64url"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 403: The connection failed the transport policy (transport_insecure, with the check in reason), or the code does not redeem: blank, unknown, used, expired, wrong verifier, or the user may no longer let a shared branch join (enrollment_refused). A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "enrollment_refused"
}

Schema:

{
  "anyOf": [
    {
      "type": "object",
      "description": "The connection failed the transport policy.",
      "required": [
        "error",
        "reason"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Always `transport_insecure`.",
          "example": "transport_insecure"
        },
        "reason": {
          "type": "string",
          "description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
          "example": "plain_http"
        }
      }
    },
    {
      "type": "object",
      "description": "The session middleware's standard body (`error`, `message`, `status`).",
      "required": [
        "error",
        "message",
        "status"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Machine slug (same as [`ErrorBody::code`]).",
          "example": "not_found"
        },
        "message": {
          "type": "string",
          "description": "Operator-facing explanation.",
          "example": "That page or resource was not found."
        },
        "status": {
          "type": "integer",
          "format": "int32",
          "description": "Numeric HTTP status (duplicates the response status for clients).",
          "example": 404,
          "minimum": 0
        }
      }
    },
    {
      "type": "object",
      "description": "The handler refused with a slug in `error`.",
      "required": [
        "error"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "What went wrong, as the handler describes it.",
          "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
        }
      }
    },
    {
      "type": "object",
      "description": "The handler refused with a slug in `error` and a sentence in `detail`.",
      "required": [
        "error",
        "detail"
      ],
      "properties": {
        "error": {
          "type": "string",
          "description": "Stable machine slug clients branch on.",
          "example": "invalid_request"
        },
        "detail": {
          "type": "string",
          "description": "What went wrong, for the person reading the answer.",
          "example": "the redirect URI must be loopback or https"
        }
      }
    }
  ],
  "description": "A `403` from a node API route: the transport policy's refusal, the standard body, or the handler's own error; the route's examples name each."
}

Status 404: The node API is not mounted on this listener (node_api_unmounted).

{
  "error": "node_api_unmounted"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 409: This library's database cannot be shared with another server (database_not_shareable).

{
  "error": "database_not_shareable"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 413: The body is larger than 16 KiB.

{
  "error": "request too large"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 415: The request is not application/json.

{
  "error": "expected application/json"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 503: The enrollment could not be read or recorded; try again (enrollment_unavailable).

{
  "error": "enrollment_unavailable"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/node/v1/connect

GET /api/node/v1/connect: upgrade to the branch-node socket after the transport check. 403 transport_insecure for a refused connection, 400 subprotocol_required without [SUBPROTOCOL].

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Responses

  • 101Switching to the branch-node WebSocket. The node's signature is checked in the first frames; a wrong one closes the socket. No body.
  • 400The request does not offer the node subprotocol (subprotocol_required). Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The transport is not allowed. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404The node API is not mounted. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 503Too many handshakes are in flight (handshakes_busy); retry after Retry-After seconds. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/node/v1/connect'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/connect'
import requests

response = requests.get("http://127.0.0.1:8787/api/node/v1/connect")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/connect");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/node/v1/connect").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 101: Switching to the branch-node WebSocket. The node's signature is checked in the first frames; a wrong one closes the socket. No body.

Status 400: The request does not offer the node subprotocol (subprotocol_required).

{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The transport is not allowed.

{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 404: The node API is not mounted.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 503: Too many handshakes are in flight (handshakes_busy); retry after Retry-After seconds.

{
  "error": "service_unavailable",
  "message": "The Bookclerk daemon is not ready to handle this request.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/node/v1/artifacts/{sha256}

GET /api/node/v1/artifacts/{sha256}.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: nodeSignature

Parameters

  • sha256pathstringrequiredArchive digest, lowercase hex.

Responses

  • 200The plugin archive. Body: BinaryBody (application/octet-stream)
  • 401The node signature is missing or wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such archive, or the node API is not mounted. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/node/v1/artifacts/<sha256>' \
    -H 'Authorization: Bookclerk-Node <node_id> <issued_at> <signature>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/artifacts/<sha256>' `
    -Headers @{ Authorization = 'Bookclerk-Node <node_id> <issued_at> <signature>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/node/v1/artifacts/<sha256>",
    headers={"Authorization": "Bookclerk-Node <node_id> <issued_at> <signature>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/artifacts/<sha256>", {
  headers: { Authorization: "Bookclerk-Node <node_id> <issued_at> <signature>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/node/v1/artifacts/<sha256>")
    .header("Authorization", "Bookclerk-Node <node_id> <issued_at> <signature>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The plugin archive. The body is binary (application/octet-stream).

Schema:

A application/octet-stream body: binary bytes.

Status 401: The node signature is missing or wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 404: No such archive, or the node API is not mounted.

{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

PUT /api/node/v1/uploads/{upload_id}/files/{index}

PUT /api/node/v1/uploads/{upload_id}/files/{index}.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: uploadToken

Parameters

  • upload_idpathstringrequiredUpload id.
  • indexpathinteger (int32)requiredFile index in the upload.
  • Content-Rangeheaderstring or nullFor a file sent in parts: bytes <first>-<last>/<size>, the part this body is, each its own request in order; or bytes */<size> with an empty body, which asks for the offset the owner needs next (to resume). A file sent whole carries no range.

Request body

application/octet-stream: BinaryBody

Responses

  • 200The file was stored (received), or a part that is not the file's last was taken, or a status query was answered, with the offset the owner needs next (partial). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 401The upload token is missing or wrong, or names no live upload (unauthorized). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 403The connection failed the transport policy (transport_insecure, with the check in reason). Body: TransportRefused (application/json)2 fields
    • errorstringrequiredAlways transport_insecure.
    • reasonstringrequiredThe transport check that refused the connection (plain_http, unknown_peer, untrusted_forwarding, proxy_proto_missing, proxy_proto_ambiguous, proxy_proto_not_https, public_origin_not_https, listener_mode_mismatch, node_api_misconfigured).
  • 404The node API is not mounted on this listener (node_api_unmounted). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409The upload lost its fence to a newer one (lost). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 421This node is not the upload's receiving node (misdirected). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 422The file was refused (refused): not in the upload (unknown_file), a Content-Range that is not exactly a part of the declared file (invalid_range), a size or content mismatch (size_mismatch, content_mismatch), the destinations changed (destinations_changed), or a granted storage key now belongs to another title or writer (key_taken). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 503Storage or the upload record is unavailable, or the file lock timed out; retry (unavailable). With reason resume, a part did not start where the open file stands, or broke part way: send the file from offset (0 when no write is open here). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.

Example request

$ curl 'http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/files/<index>' \
    -X PUT \
    -H 'Authorization: Bookclerk-Upload <token>' \
    -H 'Content-Type: application/octet-stream' \
    --data-binary @file
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/files/<index>' `
    -Method Put `
    -Headers @{ Authorization = 'Bookclerk-Upload <token>' } `
    -ContentType 'application/octet-stream' `
    -InFile 'file'
import requests

response = requests.put(
    "http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/files/<index>",
    headers={"Authorization": "Bookclerk-Upload <token>", "Content-Type": "application/octet-stream"},
    data=open("file", "rb"),
)
print(response.status_code, response.text)
import { readFile } from "node:fs/promises";

const response = await fetch("http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/files/<index>", {
  method: "PUT",
  headers: { Authorization: "Bookclerk-Upload <token>", "Content-Type": "application/octet-stream" },
  body: await readFile("file"),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .put("http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/files/<index>")
    .header("Authorization", "Bookclerk-Upload <token>")
    .header("Content-Type", "application/octet-stream")
    .body(std::fs::read("file")?)
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The file was stored (received), or a part that is not the file's last was taken, or a status query was answered, with the offset the owner needs next (partial).

{
  "job_completed": false,
  "offset": 67108864,
  "status": "partial"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 401: The upload token is missing or wrong, or names no live upload (unauthorized).

{
  "job_completed": false,
  "status": "unauthorized"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 403: The connection failed the transport policy (transport_insecure, with the check in reason).

{
  "error": "transport_insecure",
  "reason": "plain_http"
}

Schema:

{
  "type": "object",
  "description": "JSON body of a `403` from the node API's transport policy: the\nconnection is plain HTTP off loopback, or arrived through a proxy the\npolicy does not trust, and `reason` names the check that refused it.",
  "required": [
    "error",
    "reason"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Always `transport_insecure`.",
      "example": "transport_insecure"
    },
    "reason": {
      "type": "string",
      "description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
      "example": "plain_http"
    }
  }
}

Status 404: The node API is not mounted on this listener (node_api_unmounted).

{
  "error": "node_api_unmounted"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 409: The upload lost its fence to a newer one (lost).

{
  "job_completed": false,
  "status": "lost"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 421: This node is not the upload's receiving node (misdirected).

{
  "job_completed": false,
  "status": "misdirected"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 422: The file was refused (refused): not in the upload (unknown_file), a Content-Range that is not exactly a part of the declared file (invalid_range), a size or content mismatch (size_mismatch, content_mismatch), the destinations changed (destinations_changed), or a granted storage key now belongs to another title or writer (key_taken).

{
  "job_completed": false,
  "reason": "content_mismatch",
  "status": "refused"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 503: Storage or the upload record is unavailable, or the file lock timed out; retry (unavailable). With reason resume, a part did not start where the open file stands, or broke part way: send the file from offset (0 when no write is open here).

{
  "job_completed": false,
  "offset": 67108864,
  "reason": "resume",
  "status": "unavailable"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

POST /api/node/v1/uploads/{upload_id}/commit

POST /api/node/v1/uploads/{upload_id}/commit.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: uploadToken

Parameters

  • upload_idpathstringrequiredUpload id.

Request body

application/json: UploadCommitRequest

  • finishbooleanComplete the job with this commit (the job's closing upload).
  • detailstring or nullOutcome text recorded as the job's progress when finish is set.

Responses

  • 200The upload was committed to the destinations (committed). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 401The upload token is missing or wrong, or names no live upload (unauthorized). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 403The connection failed the transport policy (transport_insecure, with the check in reason). Body: TransportRefused (application/json)2 fields
    • errorstringrequiredAlways transport_insecure.
    • reasonstringrequiredThe transport check that refused the connection (plain_http, unknown_peer, untrusted_forwarding, proxy_proto_missing, proxy_proto_ambiguous, proxy_proto_not_https, public_origin_not_https, listener_mode_mismatch, node_api_misconfigured).
  • 404The node API is not mounted on this listener (node_api_unmounted). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409The upload lost its fence to a newer one (lost). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 421This node is not the upload's receiving node (misdirected). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 422The commit was refused (refused), with the cause in reason: the body does not parse (invalid_body); the upload is unknown, aborted, or its job was cancelled (unknown_upload, upload_aborted, job_cancelled); not every granted file arrived (files_missing); the destinations changed since the grant (destinations_changed); a storage key now belongs to another title or writer, or the title's holding is gone (key_taken, unknown_title); or the closing upload is mismatched: an ordinary upload claims to finish the job (not_a_closing_upload), the closing upload does not (closing_upload_must_finish), or it arrives while titles are still pending (titles_remaining). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 503Storage or the upload record is unavailable; retry (unavailable). Body: UploadAnswer (application/json)4 fields
    • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
    • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
    • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
    • job_completedbooleanFor committed: the job is finished.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/commit' \
    -X POST \
    -H 'Authorization: Bookclerk-Upload <token>' \
    -H 'Content-Type: application/json' \
    -d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/commit' `
    -Method Post `
    -Headers @{ Authorization = 'Bookclerk-Upload <token>' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/commit",
    headers={"Authorization": "Bookclerk-Upload <token>"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/commit", {
  method: "POST",
  headers: { Authorization: "Bookclerk-Upload <token>", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/commit")
    .header("Authorization", "Bookclerk-Upload <token>")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The upload was committed to the destinations (committed).

{
  "job_completed": true,
  "status": "committed"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 401: The upload token is missing or wrong, or names no live upload (unauthorized).

{
  "job_completed": false,
  "status": "unauthorized"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 403: The connection failed the transport policy (transport_insecure, with the check in reason).

{
  "error": "transport_insecure",
  "reason": "plain_http"
}

Schema:

{
  "type": "object",
  "description": "JSON body of a `403` from the node API's transport policy: the\nconnection is plain HTTP off loopback, or arrived through a proxy the\npolicy does not trust, and `reason` names the check that refused it.",
  "required": [
    "error",
    "reason"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Always `transport_insecure`.",
      "example": "transport_insecure"
    },
    "reason": {
      "type": "string",
      "description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
      "example": "plain_http"
    }
  }
}

Status 404: The node API is not mounted on this listener (node_api_unmounted).

{
  "error": "node_api_unmounted"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 409: The upload lost its fence to a newer one (lost).

{
  "job_completed": false,
  "status": "lost"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 421: This node is not the upload's receiving node (misdirected).

{
  "job_completed": false,
  "status": "misdirected"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 422: The commit was refused (refused), with the cause in reason: the body does not parse (invalid_body); the upload is unknown, aborted, or its job was cancelled (unknown_upload, upload_aborted, job_cancelled); not every granted file arrived (files_missing); the destinations changed since the grant (destinations_changed); a storage key now belongs to another title or writer, or the title's holding is gone (key_taken, unknown_title); or the closing upload is mismatched: an ordinary upload claims to finish the job (not_a_closing_upload), the closing upload does not (closing_upload_must_finish), or it arrives while titles are still pending (titles_remaining).

{
  "job_completed": false,
  "reason": "closing_upload_must_finish",
  "status": "refused"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 503: Storage or the upload record is unavailable; retry (unavailable).

{
  "job_completed": false,
  "status": "unavailable"
}

Schema:

{
  "type": "object",
  "description": "Answer of the upload endpoint (every status carries one).",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
      "example": "received"
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
      "example": "size_mismatch"
    },
    "offset": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
      "example": 67108864,
      "minimum": 0
    },
    "job_completed": {
      "type": "boolean",
      "description": "For `committed`: the job is finished.",
      "example": false
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

Generated from crates/bookclerkd/openapi.json at main · View as Markdown