bytes · management surface
Bindings
| Primary | http |
|---|---|
| HTTP | prefix /v1 |
Operations
| Name | Kind | Binding | Request | Response | Parameters | Refusals |
|---|---|---|---|---|---|---|
inventory | read | GET /v1/inventory |
Inventory | inventory_unavailable | ||
livez | operational | GET /livez |
Health | |||
healthz | operational | GET /healthz |
Health | |||
describe | operational | GET /describe |
Description | |||
describe_file | operational | GET /describe/{file...} |
file | file: string (required) | not_found |
Refusals
| Code | HTTP | Meaning |
|---|---|---|
bad_request | 400 | unexpected query parameters or request body |
not_found | 404 | the requested management contract file does not exist |
inventory_unavailable | 503 | a complete inventory observation could not be obtained; a management failure, not a content refusal |
Files served
- HTTP.md
- SURFACE.md
- openapi.json
- operations.json
- schema/Artifact.schema.json
- schema/Description.schema.json
- schema/Error.schema.json
- schema/Health.schema.json
- schema/Inventory.schema.json
SURFACE.md
Bytes management surface
Contract: 2026-09-11
The management surface observes a particular bytes instance for its operator.
It has its own listener, description and contract, independent of the nine
BN bytes content operations. The operations listener serves that separate
contract at its own /describe/SURFACE.md.
Management does not change content identity or require an index of every
implementation of the content protocol.
Inventory
inventory reads an observation of committed artifacts: their count, total
logical byte length, up to ten most recently modified objects, and up to ten
largest objects. Counts and lengths are nonnegative decimal strings. The
empty store returns zero counts and empty arrays.
Only regular files with canonical lowercase SHA-256 object paths under
objects/<first-two-hex>/<remaining-62-hex> are counted. Symlinks, temporary
uploads and unrelated files are excluded. The scan reads metadata; it neither
reads nor hashes object content, so this is not an integrity audit. Logical
byte length excludes filesystem metadata, staging files and allocation overhead.
recent orders objects by descending modification time, largest by descending
logical size. Equal values are ordered by ascending content name. Both lists
and totals come from the same scan. Successful observations may be reused for
at most five seconds, retaining their original scan timestamps. Reads are
idempotent and can be retried. Request cancellation cancels waiting or scanning.
A scan failure returns an error, never successful partial totals.
scan_started_at and observed_at bound the scan in UTC. Concurrent writes
can enter or miss the observation. This is not a transactional snapshot or an
upload history; there is no pagination, retained read view or snapshot token.
Timestamp meaning
timestamp_source is filesystem_mtime. An artifact's stored_at is the
file's modification time. The store writes a temporary file, then renames it,
preserving that timestamp. It is an approximation of when an object was added:
writing may finish before commit, and restores or external changes can alter
timestamps. Historical first-admission times are not recorded. Idempotent puts
ordinarily preserve existing objects and do not increase the artifact count.
The dashboard explains this basis and does not present it as exact upload history. The observation carries no ownership, authority, attribution, binding or custody claim.
Separation
Management is unauthenticated, like the underlying foundation. Deployment decides who can reach each listener. The separate management port allows a private management network while preserving a public content API. A deployment may explicitly publish both; no particular exposure follows from this contract.
The content listener does not serve management routes. The management listener does not serve content reads or writes. Each listener's description covers exactly its own surface.
HTTP.md
Bytes management HTTP binding
The primary binding is HTTP on a separate management listener. Paths below
are native to that listener. ULab deployment mounts this API at
/api/management, stripping that prefix before forwarding. Operations use
the separate /api/operations prefix, following the
family contract. This
does not add management routes to the content listener.
| Method and path | Operation | Success |
|---|---|---|
GET /v1/inventory |
inventory |
200, Inventory JSON |
GET /livez |
livez |
200, Health JSON |
GET /healthz |
healthz |
200 when management can read its store; 503 otherwise |
GET /describe |
describe |
200, management Description JSON |
GET /describe/{file...} |
describe_file |
200, one listed contract file verbatim |
Every response, including router errors, carries Ulab-Service: bytes,
Ulab-Surface: management and Ulab-Contract: 2026-09-11. The description has
service, surface and contract with the same values. Its operations and
files describe this listener alone. The original content listener retains its
BN description and contract date.
These routes accept no query parameters or body. Unknown, repeated or empty
query parameters, a bare trailing ?, and any request body, return 400 JSON
{"error":"bad_request"}. There is no request-size-dependent inventory limit:
the two result lists each contain at most ten records. Unsupported methods
return 405; HEAD follows GET without a response body. The route returns
503 JSON {"error":"inventory_unavailable"} when a complete observation
cannot be obtained. An unlisted description file returns 404 JSON
{"error":"not_found"}. These failures are not content-protocol refusals.
A scan has a thirty-second deadline. Successful observations are cached for at most five seconds; concurrent callers share the in-progress observation. The readiness check opens the objects directory and reads at most one entry; it does not scan the inventory.
Successful inventory responses follow Inventory.schema.json. File timestamps and the nontransactional observation are specified in SURFACE.md. The service does no content reads or hash verification for inventory.
The operational health envelope follows the family standard with the
management contract date. /livez has empty checks; /healthz describes the
management store check. Build values come from the binary's Go build metadata,
or the existing link-time variables
github.com/Bitspark/bn-bytes/impl/cloud/go/api.Revision and .Dirty.
Contract files are embedded at build and served verbatim as text/markdown
or application/json. Run go generate ./api/management from the service root
to regenerate the table, schemas and OpenAPI from the Go types and operation
table. Drift tests enforce generation and operation coverage.
Schemas
schema/Artifact.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"name": {
"pattern": "^sha256:[0-9a-f]{64}$",
"type": "string"
},
"size": {
"pattern": "^(0|[1-9][0-9]*)$",
"type": "string"
},
"stored_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"name",
"size",
"stored_at"
],
"type": "object"
}
schema/Description.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"bindings": {
"additionalProperties": false,
"properties": {
"http": {
"additionalProperties": false,
"properties": {
"prefix": {
"type": "string"
}
},
"required": [
"prefix"
],
"type": "object"
},
"primary": {
"type": "string"
}
},
"required": [
"primary",
"http"
],
"type": "object"
},
"build": {
"additionalProperties": false,
"properties": {
"dirty": {
"type": "boolean"
},
"go": {
"type": "string"
},
"revision": {
"type": "string"
}
},
"required": [
"revision",
"dirty",
"go"
],
"type": "object"
},
"contract": {
"type": "string"
},
"files": {
"items": {
"type": "string"
},
"type": "array"
},
"operations": {
"items": {
"additionalProperties": false,
"properties": {
"doc": {
"type": "string"
},
"errors": {
"items": {
"type": "string"
},
"type": "array"
},
"http": {
"additionalProperties": false,
"properties": {
"method": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"method",
"path"
],
"type": "object"
},
"kind": {
"type": "string"
},
"name": {
"type": "string"
},
"params": {
"items": {
"additionalProperties": false,
"properties": {
"doc": {
"type": "string"
},
"kind": {
"type": "string"
},
"name": {
"type": "string"
},
"required": {
"type": "boolean"
}
},
"required": [
"name",
"kind",
"required",
"doc"
],
"type": "object"
},
"type": "array"
},
"request": {
"type": "string"
},
"response": {
"type": "string"
}
},
"required": [
"name",
"kind",
"doc",
"params",
"errors",
"http"
],
"type": "object"
},
"type": "array"
},
"refusals": {
"items": {
"additionalProperties": false,
"properties": {
"http": {
"type": "integer"
},
"meaning": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"http",
"meaning"
],
"type": "object"
},
"type": "array"
},
"service": {
"type": "string"
},
"surface": {
"type": "string"
}
},
"required": [
"service",
"surface",
"contract",
"build",
"bindings",
"operations",
"refusals",
"files"
],
"type": "object"
}
schema/Error.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"error": {
"enum": [
"bad_request",
"not_found",
"inventory_unavailable"
],
"type": "string"
}
},
"required": [
"error"
],
"type": "object"
}
schema/Health.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"build": {
"additionalProperties": false,
"properties": {
"dirty": {
"type": "boolean"
},
"go": {
"type": "string"
},
"revision": {
"type": "string"
}
},
"required": [
"revision",
"dirty",
"go"
],
"type": "object"
},
"checks": {
"items": {
"additionalProperties": false,
"properties": {
"detail": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"name",
"status",
"detail"
],
"type": "object"
},
"type": "array"
},
"contract": {
"type": "string"
},
"identity": {
"additionalProperties": {},
"type": "object"
},
"service": {
"type": "string"
},
"status": {
"type": "string"
},
"time": {
"type": "string"
}
},
"required": [
"status",
"service",
"contract",
"build",
"time",
"checks"
],
"type": "object"
}
schema/Inventory.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"artifact_count": {
"pattern": "^(0|[1-9][0-9]*)$",
"type": "string"
},
"largest": {
"items": {
"additionalProperties": false,
"properties": {
"name": {
"pattern": "^sha256:[0-9a-f]{64}$",
"type": "string"
},
"size": {
"pattern": "^(0|[1-9][0-9]*)$",
"type": "string"
},
"stored_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"name",
"size",
"stored_at"
],
"type": "object"
},
"maxItems": 10,
"type": "array"
},
"observed_at": {
"format": "date-time",
"type": "string"
},
"recent": {
"items": {
"additionalProperties": false,
"properties": {
"name": {
"pattern": "^sha256:[0-9a-f]{64}$",
"type": "string"
},
"size": {
"pattern": "^(0|[1-9][0-9]*)$",
"type": "string"
},
"stored_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"name",
"size",
"stored_at"
],
"type": "object"
},
"maxItems": 10,
"type": "array"
},
"scan_started_at": {
"format": "date-time",
"type": "string"
},
"timestamp_source": {
"const": "filesystem_mtime",
"type": "string"
},
"total_bytes": {
"pattern": "^(0|[1-9][0-9]*)$",
"type": "string"
}
},
"required": [
"artifact_count",
"total_bytes",
"recent",
"largest",
"scan_started_at",
"observed_at",
"timestamp_source"
],
"type": "object"
}
OpenAPI
openapi.json (raw)
{
"components": {
"schemas": {
"Artifact": {
"additionalProperties": false,
"properties": {
"name": {
"pattern": "^sha256:[0-9a-f]{64}$",
"type": "string"
},
"size": {
"pattern": "^(0|[1-9][0-9]*)$",
"type": "string"
},
"stored_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"name",
"size",
"stored_at"
],
"type": "object"
},
"Description": {
"additionalProperties": false,
"properties": {
"bindings": {
"additionalProperties": false,
"properties": {
"http": {
"additionalProperties": false,
"properties": {
"prefix": {
"type": "string"
}
},
"required": [
"prefix"
],
"type": "object"
},
"primary": {
"type": "string"
}
},
"required": [
"primary",
"http"
],
"type": "object"
},
"build": {
"additionalProperties": false,
"properties": {
"dirty": {
"type": "boolean"
},
"go": {
"type": "string"
},
"revision": {
"type": "string"
}
},
"required": [
"revision",
"dirty",
"go"
],
"type": "object"
},
"contract": {
"type": "string"
},
"files": {
"items": {
"type": "string"
},
"type": "array"
},
"operations": {
"items": {
"additionalProperties": false,
"properties": {
"doc": {
"type": "string"
},
"errors": {
"items": {
"type": "string"
},
"type": "array"
},
"http": {
"additionalProperties": false,
"properties": {
"method": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"method",
"path"
],
"type": "object"
},
"kind": {
"type": "string"
},
"name": {
"type": "string"
},
"params": {
"items": {
"additionalProperties": false,
"properties": {
"doc": {
"type": "string"
},
"kind": {
"type": "string"
},
"name": {
"type": "string"
},
"required": {
"type": "boolean"
}
},
"required": [
"name",
"kind",
"required",
"doc"
],
"type": "object"
},
"type": "array"
},
"request": {
"type": "string"
},
"response": {
"type": "string"
}
},
"required": [
"name",
"kind",
"doc",
"params",
"errors",
"http"
],
"type": "object"
},
"type": "array"
},
"refusals": {
"items": {
"additionalProperties": false,
"properties": {
"http": {
"type": "integer"
},
"meaning": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"http",
"meaning"
],
"type": "object"
},
"type": "array"
},
"service": {
"type": "string"
},
"surface": {
"type": "string"
}
},
"required": [
"service",
"surface",
"contract",
"build",
"bindings",
"operations",
"refusals",
"files"
],
"type": "object"
},
"Error": {
"additionalProperties": false,
"properties": {
"error": {
"enum": [
"bad_request",
"not_found",
"inventory_unavailable"
],
"type": "string"
}
},
"required": [
"error"
],
"type": "object"
},
"Health": {
"additionalProperties": false,
"properties": {
"build": {
"additionalProperties": false,
"properties": {
"dirty": {
"type": "boolean"
},
"go": {
"type": "string"
},
"revision": {
"type": "string"
}
},
"required": [
"revision",
"dirty",
"go"
],
"type": "object"
},
"checks": {
"items": {
"additionalProperties": false,
"properties": {
"detail": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"name",
"status",
"detail"
],
"type": "object"
},
"type": "array"
},
"contract": {
"type": "string"
},
"identity": {
"additionalProperties": {},
"type": "object"
},
"service": {
"type": "string"
},
"status": {
"type": "string"
},
"time": {
"type": "string"
}
},
"required": [
"status",
"service",
"contract",
"build",
"time",
"checks"
],
"type": "object"
},
"Inventory": {
"additionalProperties": false,
"properties": {
"artifact_count": {
"pattern": "^(0|[1-9][0-9]*)$",
"type": "string"
},
"largest": {
"items": {
"additionalProperties": false,
"properties": {
"name": {
"pattern": "^sha256:[0-9a-f]{64}$",
"type": "string"
},
"size": {
"pattern": "^(0|[1-9][0-9]*)$",
"type": "string"
},
"stored_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"name",
"size",
"stored_at"
],
"type": "object"
},
"maxItems": 10,
"type": "array"
},
"observed_at": {
"format": "date-time",
"type": "string"
},
"recent": {
"items": {
"additionalProperties": false,
"properties": {
"name": {
"pattern": "^sha256:[0-9a-f]{64}$",
"type": "string"
},
"size": {
"pattern": "^(0|[1-9][0-9]*)$",
"type": "string"
},
"stored_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"name",
"size",
"stored_at"
],
"type": "object"
},
"maxItems": 10,
"type": "array"
},
"scan_started_at": {
"format": "date-time",
"type": "string"
},
"timestamp_source": {
"const": "filesystem_mtime",
"type": "string"
},
"total_bytes": {
"pattern": "^(0|[1-9][0-9]*)$",
"type": "string"
}
},
"required": [
"artifact_count",
"total_bytes",
"recent",
"largest",
"scan_started_at",
"observed_at",
"timestamp_source"
],
"type": "object"
}
}
},
"info": {
"title": "ULab Bytes management",
"version": "2026-09-11"
},
"openapi": "3.1.0",
"paths": {
"/describe": {
"get": {
"operationId": "describe",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Description"
}
}
},
"description": "this management surface and its build and files",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "bad_request: no query parameters or body accepted",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "this management surface and its build and files"
}
},
"/describe/{file}": {
"get": {
"operationId": "describe_file",
"parameters": [
{
"description": "a name listed by describe.files",
"in": "path",
"name": "file",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
},
"text/markdown": {
"schema": {
"type": "string"
}
}
},
"description": "one committed management contract file",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "bad_request: no query parameters or body accepted",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "not_found: the requested contract file is not listed",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "one committed management contract file"
}
},
"/healthz": {
"get": {
"operationId": "healthz",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "the management inventory can be read",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "bad_request: no query parameters or body accepted",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "the management store check failed",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "the management inventory can be read"
}
},
"/livez": {
"get": {
"operationId": "livez",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "the management listener can answer",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "bad_request: no query parameters or body accepted",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "the management listener can answer"
}
},
"/v1/inventory": {
"get": {
"operationId": "inventory",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Inventory"
}
}
},
"description": "observe artifact count, logical size, ten recent objects and ten largest objects",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "bad_request: no query parameters or body accepted",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "inventory_unavailable: a complete observation could not be obtained",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "bytes",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "observe artifact count, logical size, ten recent objects and ten largest objects"
}
}
}
}