lexicons and xrpc
lexicon
com.publicdomainrelay.temp.cluster.subscribeClusters
The gateway streams the calling account's cluster state as an atproto event stream (binary WebSocket frames, each a DRISL-CBOR header then a DRISL-CBOR payload). Authenticate on the upgrade request with the normal service-auth token (Authorization: Bearer, lxm = this method). The account comes from the verified token's iss only. The token is verified once, at connect; a healthy stream is not cut when the token's exp passes. The stream ends when the client closes, when the gateway restarts, or at the gateway's stream lifetime bound (1 h by default) with a TokenExpired error frame; reconnect with a fresh token. There is no seq and no cursor: every connect starts with a snapshot (one #cluster message per matching cluster, one #member per control-plane member, one #nodeClaim per NodeClaim, each with snapshot=true), then one #info named SnapshotComplete, then live changes read from kcp watches.
definitions: #cluster #member #nodeClaim #info
parameters
| parameter | type | description |
|---|---|---|
name | string | Only this cluster. Unknown name: ClusterNotFound error frame, then close. Absent: every cluster of the account, including clusters created while the stream is open. maxLength 63 |
message
union #cluster | #member | #nodeClaim | #info
errors
| error | description |
|---|---|
InvalidRequest | The parameters are malformed. |
Unauthorized | Missing or invalid service-auth token, or its aud or lxm is not this service or method. |
TokenExpired | The token was expired at connect, or the stream reached the gateway's lifetime bound. Get a fresh token and reconnect. |
ClusterNotFound | The named cluster does not exist, was deleted while the stream was open, or the account has no clusters yet (call createCluster first). |
IdentityRevoked | The account's identity is revoked; the caller lost access. |
ClusterUnavailable | The gateway could not read or watch its kcp. |
ConsumerTooSlow | The client did not read frames fast enough. |
MethodNotAllowed | 405, as HTTP JSON before any upgrade: the request is not a GET. |
UpgradeRequired | 426, as HTTP JSON before any upgrade: the request is not a WebSocket upgrade. |
RateLimitExceeded | 429 with Retry-After, as HTTP JSON before any upgrade: the caller already has as many streams open as the gateway allows (StreamsPerCaller, 8 by default). |
#cluster object
| field | type | description |
|---|---|---|
name * | string | |
phase * | string | knownValues ["Unavailable","Initializing","Ready","Draining"] |
running | boolean | The desired state (spec.running). |
instance | string | |
server | string | status.URL. Absent until the apiserver has answered once. |
reason | string | The reason of the condition that explains the phase (Ready, or IdentityVerificationFailed or TeardownBlocked when true). |
message | string | That condition's message; names the members that are not running when the phase is Initializing. |
teardownBlocked | boolean | |
deleted | boolean | The cluster is gone. |
snapshot | boolean | Sent as part of the connect snapshot, not as a change. |
time * | string datetime | When the gateway saw this state. |
#member object
| field | type | description |
|---|---|---|
cluster * | string | |
member * | string | The control-plane member (postgres, openbao, kine, k3s, ...), read from its HostProcess, Postgres or OpenBaoServer object. Members start one after another. |
phase * | string | knownValues ["Pending","Starting","Running","Ready","Sealed","Stopping","Stopped","Deleting","Failed","Lost"] |
reason | string | Why the member was lost, when it was. |
message | string | |
deleted | boolean | |
snapshot | boolean | |
time * | string datetime |
#nodeClaim object
| field | type | description |
|---|---|---|
cluster * | string | |
name * | string | |
nodeName | string | |
phase * | string | knownValues ["Pending","Bidding","Provisioning","Joining","Running","Failed","Released","Lost","Adopting"] |
message | string | Why the claim is in its phase; carries the provision failure. |
contractPhase | string | |
outcome | string | |
bidder | string | The DID of the winning bidder. |
fqdn | string | |
deleted | boolean | |
snapshot | boolean | |
time * | string datetime |
#info object
| field | type | description |
|---|---|---|
name * | string | knownValues ["SnapshotComplete"] |
message | string |
used in
no page of these docs names it yet.
raw schema: lexicons/com/publicdomainrelay/temp/cluster/subscribeClusters.json
{
"lexicon": 1,
"id": "com.publicdomainrelay.temp.cluster.subscribeClusters",
"defs": {
"main": {
"type": "subscription",
"description": "The gateway streams the calling account's cluster state as an atproto event stream (binary WebSocket frames, each a DRISL-CBOR header then a DRISL-CBOR payload). Authenticate on the upgrade request with the normal service-auth token (Authorization: Bearer, lxm = this method). The account comes from the verified token's iss only. The token is verified once, at connect; a healthy stream is not cut when the token's exp passes. The stream ends when the client closes, when the gateway restarts, or at the gateway's stream lifetime bound (1 h by default) with a TokenExpired error frame; reconnect with a fresh token. There is no seq and no cursor: every connect starts with a snapshot (one #cluster message per matching cluster, one #member per control-plane member, one #nodeClaim per NodeClaim, each with snapshot=true), then one #info named SnapshotComplete, then live changes read from kcp watches.",
"parameters": {
"type": "params",
"properties": {
"name": {
"type": "string",
"maxLength": 63,
"description": "Only this cluster. Unknown name: ClusterNotFound error frame, then close. Absent: every cluster of the account, including clusters created while the stream is open."
}
}
},
"message": {
"schema": {
"type": "union",
"refs": [
"#cluster",
"#member",
"#nodeClaim",
"#info"
]
}
},
"errors": [
{
"name": "InvalidRequest",
"description": "The parameters are malformed."
},
{
"name": "Unauthorized",
"description": "Missing or invalid service-auth token, or its aud or lxm is not this service or method."
},
{
"name": "TokenExpired",
"description": "The token was expired at connect, or the stream reached the gateway's lifetime bound. Get a fresh token and reconnect."
},
{
"name": "ClusterNotFound",
"description": "The named cluster does not exist, was deleted while the stream was open, or the account has no clusters yet (call createCluster first)."
},
{
"name": "IdentityRevoked",
"description": "The account's identity is revoked; the caller lost access."
},
{
"name": "ClusterUnavailable",
"description": "The gateway could not read or watch its kcp."
},
{
"name": "ConsumerTooSlow",
"description": "The client did not read frames fast enough."
},
{
"name": "MethodNotAllowed",
"description": "405, as HTTP JSON before any upgrade: the request is not a GET."
},
{
"name": "UpgradeRequired",
"description": "426, as HTTP JSON before any upgrade: the request is not a WebSocket upgrade."
},
{
"name": "RateLimitExceeded",
"description": "429 with Retry-After, as HTTP JSON before any upgrade: the caller already has as many streams open as the gateway allows (StreamsPerCaller, 8 by default)."
}
]
},
"cluster": {
"type": "object",
"required": [
"name",
"phase",
"time"
],
"properties": {
"name": {
"type": "string"
},
"phase": {
"type": "string",
"knownValues": [
"Unavailable",
"Initializing",
"Ready",
"Draining"
]
},
"running": {
"type": "boolean",
"description": "The desired state (spec.running)."
},
"instance": {
"type": "string"
},
"server": {
"type": "string",
"description": "status.URL. Absent until the apiserver has answered once."
},
"reason": {
"type": "string",
"description": "The reason of the condition that explains the phase (Ready, or IdentityVerificationFailed or TeardownBlocked when true)."
},
"message": {
"type": "string",
"description": "That condition's message; names the members that are not running when the phase is Initializing."
},
"teardownBlocked": {
"type": "boolean"
},
"deleted": {
"type": "boolean",
"description": "The cluster is gone."
},
"snapshot": {
"type": "boolean",
"description": "Sent as part of the connect snapshot, not as a change."
},
"time": {
"type": "string",
"format": "datetime",
"description": "When the gateway saw this state."
}
}
},
"member": {
"type": "object",
"required": [
"cluster",
"member",
"phase",
"time"
],
"properties": {
"cluster": {
"type": "string"
},
"member": {
"type": "string",
"description": "The control-plane member (postgres, openbao, kine, k3s, ...), read from its HostProcess, Postgres or OpenBaoServer object. Members start one after another."
},
"phase": {
"type": "string",
"knownValues": [
"Pending",
"Starting",
"Running",
"Ready",
"Sealed",
"Stopping",
"Stopped",
"Deleting",
"Failed",
"Lost"
]
},
"reason": {
"type": "string",
"description": "Why the member was lost, when it was."
},
"message": {
"type": "string"
},
"deleted": {
"type": "boolean"
},
"snapshot": {
"type": "boolean"
},
"time": {
"type": "string",
"format": "datetime"
}
}
},
"nodeClaim": {
"type": "object",
"required": [
"cluster",
"name",
"phase",
"time"
],
"properties": {
"cluster": {
"type": "string"
},
"name": {
"type": "string"
},
"nodeName": {
"type": "string"
},
"phase": {
"type": "string",
"knownValues": [
"Pending",
"Bidding",
"Provisioning",
"Joining",
"Running",
"Failed",
"Released",
"Lost",
"Adopting"
]
},
"message": {
"type": "string",
"description": "Why the claim is in its phase; carries the provision failure."
},
"contractPhase": {
"type": "string"
},
"outcome": {
"type": "string"
},
"bidder": {
"type": "string",
"description": "The DID of the winning bidder."
},
"fqdn": {
"type": "string"
},
"deleted": {
"type": "boolean"
},
"snapshot": {
"type": "boolean"
},
"time": {
"type": "string",
"format": "datetime"
}
}
},
"info": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"knownValues": [
"SnapshotComplete"
]
},
"message": {
"type": "string"
}
}
}
}
}