lexicons and xrpc
lexicon
com.publicdomainrelay.temp.cluster.listClusters
The gateway lists the calling account's clusters. The account comes from the verified token's iss, so this never takes a DID and can never be used to look at another account. This is a user verb, not an internal one: the gateway's own need to enumerate an account's workspaces is satisfied by a list against kcp with its own privileged credential, not by this call. UNPAGINATED, and it declares no parameters because it has none: an account's clusters are read as one Workspace list plus a CR read per cluster, so a page of clusters is not a page of anything the store can page. There is no limit and no cursor, and a request carrying either is not refused - undeclared query parameters are ignored. If paging is ever implemented, limit and cursor return as new OPTIONAL parameters and a cursor as a new optional output field.
definitions: #clusterItem
output
| field | type | description |
|---|---|---|
clusters * | array of #clusterItem |
errors
| error | description |
|---|---|
InvalidRequest | The request is malformed. |
Unauthorized | Missing or invalid service-auth token. Also returned when the token's aud is not this service or its lxm is not this method. |
ClusterUnavailable | 503: the gateway could not resolve the token issuer's signing key in time. Retry. |
InternalError | 500: a failure the gateway maps to no named error. |
#clusterItem object
| field | type | description |
|---|---|---|
name * | string | The cluster label. |
phase * | string | Unavailable is COLD: the store is retained and controlPlaneUp will bring it back. Draining means teardown has begun and the gate is running. knownValues ["Unavailable","Initializing","Ready","Draining"] |
running | boolean | The desired state, as distinct from the phase: a cluster can be running=false and still Initializing out of an earlier request. |
instance | string | status.instance for this materialisation; changes on every wake and rebuild. |
teardownBlocked | boolean | True when the teardown gate timed out. Nothing has been destroyed and an operator has to act; this is the only place that outcome is visible. Absent means no source reports it, which for a cluster that is not Draining is the same thing as false; it is never sent as false, because a false would be a claim about a condition nothing has read. |
server | string | status.URL: the cluster's endpoint. Empty until the apiserver has answered at least once. |
used in
no page of these docs names it yet.
raw schema: lexicons/com/publicdomainrelay/temp/cluster/listClusters.json
{
"lexicon": 1,
"id": "com.publicdomainrelay.temp.cluster.listClusters",
"defs": {
"main": {
"type": "query",
"description": "The gateway lists the calling account's clusters. The account comes from the verified token's iss, so this never takes a DID and can never be used to look at another account. This is a user verb, not an internal one: the gateway's own need to enumerate an account's workspaces is satisfied by a list against kcp with its own privileged credential, not by this call. UNPAGINATED, and it declares no parameters because it has none: an account's clusters are read as one Workspace list plus a CR read per cluster, so a page of clusters is not a page of anything the store can page. There is no limit and no cursor, and a request carrying either is not refused - undeclared query parameters are ignored. If paging is ever implemented, limit and cursor return as new OPTIONAL parameters and a cursor as a new optional output field.",
"output": {
"encoding": "application/json",
"schema": {
"type": "object",
"required": [
"clusters"
],
"properties": {
"clusters": {
"type": "array",
"items": {
"type": "ref",
"ref": "#clusterItem"
}
}
}
}
},
"errors": [
{
"name": "InvalidRequest",
"description": "The request is malformed."
},
{
"name": "Unauthorized",
"description": "Missing or invalid service-auth token. Also returned when the token's aud is not this service or its lxm is not this method."
},
{
"name": "ClusterUnavailable",
"description": "503: the gateway could not resolve the token issuer's signing key in time. Retry."
},
{
"name": "InternalError",
"description": "500: a failure the gateway maps to no named error."
}
]
},
"clusterItem": {
"type": "object",
"required": [
"name",
"phase"
],
"properties": {
"name": {
"type": "string",
"description": "The cluster label."
},
"phase": {
"type": "string",
"knownValues": [
"Unavailable",
"Initializing",
"Ready",
"Draining"
],
"description": "Unavailable is COLD: the store is retained and controlPlaneUp will bring it back. Draining means teardown has begun and the gate is running."
},
"running": {
"type": "boolean",
"description": "The desired state, as distinct from the phase: a cluster can be running=false and still Initializing out of an earlier request."
},
"instance": {
"type": "string",
"description": "status.instance for this materialisation; changes on every wake and rebuild."
},
"teardownBlocked": {
"type": "boolean",
"description": "True when the teardown gate timed out. Nothing has been destroyed and an operator has to act; this is the only place that outcome is visible. Absent means no source reports it, which for a cluster that is not Draining is the same thing as false; it is never sent as false, because a false would be a claim about a condition nothing has read."
},
"server": {
"type": "string",
"description": "status.URL: the cluster's endpoint. Empty until the apiserver has answered at least once."
}
}
}
}
}