socialweb.computer

Request and provide VMs on an atproto compute market.

lexicons and xrpc

lexicon

com.publicdomainrelay.temp.cluster.subscribeClusters

subscription WebSocket /xrpc/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

parametertypedescription
namestring
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

errordescription
InvalidRequestThe parameters are malformed.
UnauthorizedMissing or invalid service-auth token, or its aud or lxm is not this service or method.
TokenExpiredThe token was expired at connect, or the stream reached the gateway's lifetime bound. Get a fresh token and reconnect.
ClusterNotFoundThe named cluster does not exist, was deleted while the stream was open, or the account has no clusters yet (call createCluster first).
IdentityRevokedThe account's identity is revoked; the caller lost access.
ClusterUnavailableThe gateway could not read or watch its kcp.
ConsumerTooSlowThe client did not read frames fast enough.
MethodNotAllowed405, as HTTP JSON before any upgrade: the request is not a GET.
UpgradeRequired426, as HTTP JSON before any upgrade: the request is not a WebSocket upgrade.
RateLimitExceeded429 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

fieldtypedescription
name *string
phase *string
knownValues ["Unavailable","Initializing","Ready","Draining"]
runningboolean
The desired state (spec.running).
instancestring
serverstring
status.URL. Absent until the apiserver has answered once.
reasonstring
The reason of the condition that explains the phase (Ready, or IdentityVerificationFailed or TeardownBlocked when true).
messagestring
That condition's message; names the members that are not running when the phase is Initializing.
teardownBlockedboolean
deletedboolean
The cluster is gone.
snapshotboolean
Sent as part of the connect snapshot, not as a change.
time *string datetime
When the gateway saw this state.

#member object

fieldtypedescription
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"]
reasonstring
Why the member was lost, when it was.
messagestring
deletedboolean
snapshotboolean
time *string datetime

#nodeClaim object

fieldtypedescription
cluster *string
name *string
nodeNamestring
phase *string
knownValues ["Pending","Bidding","Provisioning","Joining","Running","Failed","Released","Lost","Adopting"]
messagestring
Why the claim is in its phase; carries the provision failure.
contractPhasestring
outcomestring
bidderstring
The DID of the winning bidder.
fqdnstring
deletedboolean
snapshotboolean
time *string datetime

#info object

fieldtypedescription
name *string
knownValues ["SnapshotComplete"]
messagestring

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"
        }
      }
    }
  }
}