lexicons and xrpc
lexicon
com.fedproxy.temp.xrpc.subscribe
The subscriber's WebSocket to the did:key ingress relay (the Go relay `socialweb-computer internal ingress-relay`, at xrpc.fedproxy.com): a bidder or requester holds it open so that HTTP requests and WebSocket subscriptions sent to its host, <did label>.<relay hostname>, are carried to it and answered over this socket. Served on the relay's own hostname only, as a GET with a WebSocket upgrade. Before it, the subscriber gets a nonce from com.fedproxy.temp.xrpc.getRegistrationNonce, signs the nonce bytes and puts the signed com.fedproxy.temp.xrpc.registration in the registration parameter. Authentication is a service-auth JWT (ES256K or ES256, aud did:web:<relay hostname>, lxm com.fedproxy.temp.xrpc.subscribe, exp required, 5 s leeway) in the Authorization header as Bearer, or in the service_auth parameter when the client cannot set headers (a browser). After the upgrade the relay checks the registration (nonce known, unexpired and issued for registration.key, one signature that verifies over the nonce bytes), that did equals registration.key, and its own DID allowlist when one is configured; a failure closes the socket with code 1008 and the reason (did query param must be a DID, malformed registration, registration rejected: <reason>, did does not match registration key, DID not in allowlist). On success the relay sends #registered; a later subscriber with the same DID replaces the earlier one. Unlike the XRPC event-stream framing (CBOR header and body in binary frames), every message in both directions is one JSON text frame, an object whose $type names its kind: com.fedproxy.temp.xrpc.subscribe#<kind> for the frames here, com.fedproxy.temp.xrpc.alias and com.fedproxy.temp.xrpc.alias#result for custom domains. The relay also parses binary frames as JSON; a frame that is not JSON, or of a kind it does not know, is ignored. A frame is at most 64 MiB. Every 5 s the relay sends a #request GET /xrpc/com.publicdomainrelay.temp.keepalive.ping that the subscriber must answer with a #response; a subscriber that has answered nothing for 90 s is closed with code 1011 (subscriber unresponsive for <n>s). The connection lives as long as the service-auth token: the relay closes it with code 1008 (service auth token expired) at the token's exp unless a #renew with a newer token came first, and with code 1001 (server shutting down) when it stops.
definitions: #registered #renew #renewed #request #response #subscribe #subscriptionOpen #subscriptionEvent #subscriptionData #subscriptionClose #subscriptionCancel
parameters
| parameter | type | description |
|---|---|---|
did * | string did | The subscriber's DID; it must equal registration.key. Its label (the DID lowercased, every colon replaced by a hyphen) is the subscriber's subdomain under the relay hostname. |
registration * | string | The signed com.fedproxy.temp.xrpc.registration object, as JSON text (URL-encoded in the query). |
service_auth | string | The service-auth JWT for lxm com.fedproxy.temp.xrpc.subscribe, used only when there is no Authorization header. |
message
union #registered | #renew | #renewed | #request | #response | #subscribe | #subscriptionOpen | #subscriptionEvent | #subscriptionData | #subscriptionClose | #subscriptionCancel | com.fedproxy.temp.xrpc.alias | com.fedproxy.temp.xrpc.alias#result
errors
| error | description |
|---|---|
AuthenticationRequired | 401, as HTTP JSON {error, message} before the upgrade: the Authorization header is not Bearer <token>, there is no token at all, or the service-auth token does not verify (signature, aud, lxm, exp). |
NoSubscriber | 503, as HTTP JSON to a caller of a subscriber's host (not on this socket): no subscriber holds that host now. A WebSocket caller of such a host is instead closed with code 4004 (no active subscriber for subdomain <label>). |
RelayError | 502, as HTTP JSON to a caller of a subscriber's host: the subscriber did not answer the #request in time (30 s by default: relay timeout after <n>ms), or the frame could not be written to it. |
PayloadTooLarge | 413, as HTTP JSON to a caller of a subscriber's host: the request body is over the relay's limit (32 MiB by default); no #request is sent. |
#registered object
Sent by the relay once, right after the upgrade, when the registration is accepted; the subscriber waits for it (30 s) before it reads anything else.
| field | type | description |
|---|---|---|
subdomain * | string | The subscriber's DID label (lowercased, colons as hyphens); its public host is <subdomain>.<relay hostname>. |
ingressRef * | string did | did:web:<subdomain>.<relay hostname>, the subscriber's ingress identity. |
#renew object
Sent by the subscriber before its service-auth token expires (a minute before, or a fifth of the time left when that is shorter) to extend the connection to a new token's exp.
| field | type | description |
|---|---|---|
serviceAuth * | string | A new service-auth JWT for lxm com.fedproxy.temp.xrpc.subscribe whose issuer is the subscriber's DID. A token that does not verify, or of another issuer, is logged and ignored: no frame answers it. |
#renewed object
Sent by the relay when a #renew was accepted; the connection now lives until the new token's exp.
| field | type | description |
|---|---|---|
subdomain * | string | The subscriber's DID label. |
#request object
Sent by the relay for each HTTP request to the subscriber's host (and for the keepalive): the subscriber answers it with one #response of the same requestId.
| field | type | description |
|---|---|---|
requestId * | string | The relay's id for this request: 32 hex characters (16 random bytes). |
method * | string | The HTTP method, as the caller sent it (GET, POST, ...). |
path * | string | The request path, URL-escaped as received, with its /xrpc/ prefix (for example /xrpc/com.publicdomainrelay.temp.market.submitBid); the keepalive's is /xrpc/com.publicdomainrelay.temp.keepalive.ping. |
params * | unknown | The query parameters: an object of parameter name to string; a parameter given more than once has its last value. |
headers * | unknown | The request headers: an object of lowercased header name to string (repeated values joined with ", "), with host added from the request when absent. A subscriber also accepts an array of strings as a value. |
body | unknown nullable | The request body parsed as JSON. Present for every method but GET and HEAD; null when the body is not JSON (rawBody holds it) and in the keepalive request. |
rawBody | string | The request body as text, for every method but GET and HEAD. |
#response object
Sent by the subscriber to answer a #request; the relay writes it to the HTTP caller. A response for an unknown or timed-out requestId is dropped.
| field | type | description |
|---|---|---|
requestId * | string | The requestId of the #request this answers. |
status | integer | The HTTP status; absent or 0 means 200. A subscriber whose handler failed sends 500 with body {error: InternalError, message}. |
contentType | string | The Content-Type of the answer (default application/json); it wins over a Content-Type in headers. |
body | unknown | The answer as a JSON value, written as its JSON text; a JSON string is written as the string's own text. |
rawBody | string | The answer as text, used by the relay only when body is absent or null. |
bodyBase64 | string | The answer's bytes, standard base64 with padding; when present it wins over body. The subscriber sends it when its answer is not valid JSON. |
headers | unknown | Optional response headers: an object of header name to a string, or to an array of strings (Set-Cookie). The relay drops hop-by-hop headers, Content-Length, Strict-Transport-Security, Alt-Svc, Proxy-*, a Set-Cookie with a Domain attribute, invalid names and values (CR, LF, NUL and other controls), values over 8 KiB, and everything past 64 values or 32 KiB. |
#subscribe object
Sent by the relay when a caller opens a WebSocket to /xrpc/<nsid> on the subscriber's host: the subscriber starts that subscription and answers #subscriptionOpen, or #subscriptionClose when it cannot. Everything the caller sends on it then comes as #subscriptionData.
| field | type | description |
|---|---|---|
subscriptionId * | string | The relay's id for this subscription: 32 hex characters (16 random bytes). |
nsid * | string | The path after /xrpc/ as the caller sent it, URL-escaped: an XRPC subscription NSID, or com.fedproxy.temp.xrpc.tunnel for a TCP tunnel. |
params * | unknown | The caller's query parameters: an object of parameter name to string (last value of a repeated one). |
headers * | unknown | The caller's authorization and atproto-proxy headers, when it sent them: an object of lowercased header name to string. |
#subscriptionOpen object
Sent by the subscriber once a subscription is running (its upstream WebSocket is dialed, its handler started, or its tunnel's TCP connection is open); the relay reads nothing from it.
| field | type | description |
|---|---|---|
subscriptionId * | string | The subscriptionId of the #subscribe. |
#subscriptionEvent object
Sent by the subscriber for one JSON message of a subscription; the relay writes message to the caller as one text frame.
| field | type | description |
|---|---|---|
subscriptionId * | string | The subscriptionId of the #subscribe. |
message * | unknown | The message, any JSON value; the caller gets its JSON text as is. |
#subscriptionData object
Bytes of a subscription, in either direction: from the relay, one message the caller sent (text or binary); from the subscriber, one binary message for the caller (an event-stream frame, or a chunk of a tunnel's TCP stream). A caller that reads too slowly (4096 messages queued) is closed with code 1008 (consumer too slow).
| field | type | description |
|---|---|---|
subscriptionId * | string | The subscriptionId of the #subscribe. |
data * | string | The bytes, standard base64 with padding; data that does not decode is dropped. |
#subscriptionClose object
Sent by the subscriber when a subscription ends (its upstream closed, its dial failed, its tunnel's TCP connection ended); the relay closes the caller's WebSocket with the code and reason. The relay handles a #subscriptionCancel from the subscriber the same way.
| field | type | description |
|---|---|---|
subscriptionId * | string | The subscriptionId of the #subscribe. |
code | integer | The WebSocket close code for the caller; absent or 0 means 1000. A code outside 1000-1003, 1007-1014 and 3000-4999 is sent as 1000. The subscriber sends 1011 for a failed dial or handler. |
reason | string | The close reason for the caller, cut to 123 bytes. |
#subscriptionCancel object
Sent by the relay when the caller's WebSocket closed: the subscriber stops that subscription. The subscriber handles a #subscriptionClose from the relay the same way. When the subscriber itself goes away, the relay closes its callers with code 4004 (subscriber disconnected).
| field | type | description |
|---|---|---|
subscriptionId * | string | The subscriptionId of the #subscribe. |
reason | string | Why the relay cancelled it. knownValues ["caller disconnected"] |
used in
no page of these docs names it yet.
raw schema: lexicons/com/fedproxy/temp/xrpc/subscribe.json
{
"lexicon": 1,
"id": "com.fedproxy.temp.xrpc.subscribe",
"defs": {
"main": {
"type": "subscription",
"description": "The subscriber's WebSocket to the did:key ingress relay (the Go relay `socialweb-computer internal ingress-relay`, at xrpc.fedproxy.com): a bidder or requester holds it open so that HTTP requests and WebSocket subscriptions sent to its host, <did label>.<relay hostname>, are carried to it and answered over this socket. Served on the relay's own hostname only, as a GET with a WebSocket upgrade. Before it, the subscriber gets a nonce from com.fedproxy.temp.xrpc.getRegistrationNonce, signs the nonce bytes and puts the signed com.fedproxy.temp.xrpc.registration in the registration parameter. Authentication is a service-auth JWT (ES256K or ES256, aud did:web:<relay hostname>, lxm com.fedproxy.temp.xrpc.subscribe, exp required, 5 s leeway) in the Authorization header as Bearer, or in the service_auth parameter when the client cannot set headers (a browser). After the upgrade the relay checks the registration (nonce known, unexpired and issued for registration.key, one signature that verifies over the nonce bytes), that did equals registration.key, and its own DID allowlist when one is configured; a failure closes the socket with code 1008 and the reason (did query param must be a DID, malformed registration, registration rejected: <reason>, did does not match registration key, DID not in allowlist). On success the relay sends #registered; a later subscriber with the same DID replaces the earlier one. Unlike the XRPC event-stream framing (CBOR header and body in binary frames), every message in both directions is one JSON text frame, an object whose $type names its kind: com.fedproxy.temp.xrpc.subscribe#<kind> for the frames here, com.fedproxy.temp.xrpc.alias and com.fedproxy.temp.xrpc.alias#result for custom domains. The relay also parses binary frames as JSON; a frame that is not JSON, or of a kind it does not know, is ignored. A frame is at most 64 MiB. Every 5 s the relay sends a #request GET /xrpc/com.publicdomainrelay.temp.keepalive.ping that the subscriber must answer with a #response; a subscriber that has answered nothing for 90 s is closed with code 1011 (subscriber unresponsive for <n>s). The connection lives as long as the service-auth token: the relay closes it with code 1008 (service auth token expired) at the token's exp unless a #renew with a newer token came first, and with code 1001 (server shutting down) when it stops.",
"parameters": {
"type": "params",
"required": [
"did",
"registration"
],
"properties": {
"did": {
"type": "string",
"format": "did",
"description": "The subscriber's DID; it must equal registration.key. Its label (the DID lowercased, every colon replaced by a hyphen) is the subscriber's subdomain under the relay hostname."
},
"registration": {
"type": "string",
"description": "The signed com.fedproxy.temp.xrpc.registration object, as JSON text (URL-encoded in the query)."
},
"service_auth": {
"type": "string",
"description": "The service-auth JWT for lxm com.fedproxy.temp.xrpc.subscribe, used only when there is no Authorization header."
}
}
},
"message": {
"schema": {
"type": "union",
"refs": [
"#registered",
"#renew",
"#renewed",
"#request",
"#response",
"#subscribe",
"#subscriptionOpen",
"#subscriptionEvent",
"#subscriptionData",
"#subscriptionClose",
"#subscriptionCancel",
"com.fedproxy.temp.xrpc.alias",
"com.fedproxy.temp.xrpc.alias#result"
]
}
},
"errors": [
{
"name": "AuthenticationRequired",
"description": "401, as HTTP JSON {error, message} before the upgrade: the Authorization header is not Bearer <token>, there is no token at all, or the service-auth token does not verify (signature, aud, lxm, exp)."
},
{
"name": "NoSubscriber",
"description": "503, as HTTP JSON to a caller of a subscriber's host (not on this socket): no subscriber holds that host now. A WebSocket caller of such a host is instead closed with code 4004 (no active subscriber for subdomain <label>)."
},
{
"name": "RelayError",
"description": "502, as HTTP JSON to a caller of a subscriber's host: the subscriber did not answer the #request in time (30 s by default: relay timeout after <n>ms), or the frame could not be written to it."
},
{
"name": "PayloadTooLarge",
"description": "413, as HTTP JSON to a caller of a subscriber's host: the request body is over the relay's limit (32 MiB by default); no #request is sent."
}
]
},
"registered": {
"type": "object",
"description": "Sent by the relay once, right after the upgrade, when the registration is accepted; the subscriber waits for it (30 s) before it reads anything else.",
"required": [
"subdomain",
"ingressRef"
],
"properties": {
"subdomain": {
"type": "string",
"description": "The subscriber's DID label (lowercased, colons as hyphens); its public host is <subdomain>.<relay hostname>."
},
"ingressRef": {
"type": "string",
"format": "did",
"description": "did:web:<subdomain>.<relay hostname>, the subscriber's ingress identity."
}
}
},
"renew": {
"type": "object",
"description": "Sent by the subscriber before its service-auth token expires (a minute before, or a fifth of the time left when that is shorter) to extend the connection to a new token's exp.",
"required": [
"serviceAuth"
],
"properties": {
"serviceAuth": {
"type": "string",
"description": "A new service-auth JWT for lxm com.fedproxy.temp.xrpc.subscribe whose issuer is the subscriber's DID. A token that does not verify, or of another issuer, is logged and ignored: no frame answers it."
}
}
},
"renewed": {
"type": "object",
"description": "Sent by the relay when a #renew was accepted; the connection now lives until the new token's exp.",
"required": [
"subdomain"
],
"properties": {
"subdomain": {
"type": "string",
"description": "The subscriber's DID label."
}
}
},
"request": {
"type": "object",
"description": "Sent by the relay for each HTTP request to the subscriber's host (and for the keepalive): the subscriber answers it with one #response of the same requestId.",
"required": [
"requestId",
"method",
"path",
"params",
"headers"
],
"nullable": [
"body"
],
"properties": {
"requestId": {
"type": "string",
"description": "The relay's id for this request: 32 hex characters (16 random bytes)."
},
"method": {
"type": "string",
"description": "The HTTP method, as the caller sent it (GET, POST, ...)."
},
"path": {
"type": "string",
"description": "The request path, URL-escaped as received, with its /xrpc/ prefix (for example /xrpc/com.publicdomainrelay.temp.market.submitBid); the keepalive's is /xrpc/com.publicdomainrelay.temp.keepalive.ping."
},
"params": {
"type": "unknown",
"description": "The query parameters: an object of parameter name to string; a parameter given more than once has its last value."
},
"headers": {
"type": "unknown",
"description": "The request headers: an object of lowercased header name to string (repeated values joined with \", \"), with host added from the request when absent. A subscriber also accepts an array of strings as a value."
},
"body": {
"type": "unknown",
"description": "The request body parsed as JSON. Present for every method but GET and HEAD; null when the body is not JSON (rawBody holds it) and in the keepalive request."
},
"rawBody": {
"type": "string",
"description": "The request body as text, for every method but GET and HEAD."
}
}
},
"response": {
"type": "object",
"description": "Sent by the subscriber to answer a #request; the relay writes it to the HTTP caller. A response for an unknown or timed-out requestId is dropped.",
"required": [
"requestId"
],
"properties": {
"requestId": {
"type": "string",
"description": "The requestId of the #request this answers."
},
"status": {
"type": "integer",
"description": "The HTTP status; absent or 0 means 200. A subscriber whose handler failed sends 500 with body {error: InternalError, message}."
},
"contentType": {
"type": "string",
"description": "The Content-Type of the answer (default application/json); it wins over a Content-Type in headers."
},
"body": {
"type": "unknown",
"description": "The answer as a JSON value, written as its JSON text; a JSON string is written as the string's own text."
},
"rawBody": {
"type": "string",
"description": "The answer as text, used by the relay only when body is absent or null."
},
"bodyBase64": {
"type": "string",
"description": "The answer's bytes, standard base64 with padding; when present it wins over body. The subscriber sends it when its answer is not valid JSON."
},
"headers": {
"type": "unknown",
"description": "Optional response headers: an object of header name to a string, or to an array of strings (Set-Cookie). The relay drops hop-by-hop headers, Content-Length, Strict-Transport-Security, Alt-Svc, Proxy-*, a Set-Cookie with a Domain attribute, invalid names and values (CR, LF, NUL and other controls), values over 8 KiB, and everything past 64 values or 32 KiB."
}
}
},
"subscribe": {
"type": "object",
"description": "Sent by the relay when a caller opens a WebSocket to /xrpc/<nsid> on the subscriber's host: the subscriber starts that subscription and answers #subscriptionOpen, or #subscriptionClose when it cannot. Everything the caller sends on it then comes as #subscriptionData.",
"required": [
"subscriptionId",
"nsid",
"params",
"headers"
],
"properties": {
"subscriptionId": {
"type": "string",
"description": "The relay's id for this subscription: 32 hex characters (16 random bytes)."
},
"nsid": {
"type": "string",
"description": "The path after /xrpc/ as the caller sent it, URL-escaped: an XRPC subscription NSID, or com.fedproxy.temp.xrpc.tunnel for a TCP tunnel."
},
"params": {
"type": "unknown",
"description": "The caller's query parameters: an object of parameter name to string (last value of a repeated one)."
},
"headers": {
"type": "unknown",
"description": "The caller's authorization and atproto-proxy headers, when it sent them: an object of lowercased header name to string."
}
}
},
"subscriptionOpen": {
"type": "object",
"description": "Sent by the subscriber once a subscription is running (its upstream WebSocket is dialed, its handler started, or its tunnel's TCP connection is open); the relay reads nothing from it.",
"required": [
"subscriptionId"
],
"properties": {
"subscriptionId": {
"type": "string",
"description": "The subscriptionId of the #subscribe."
}
}
},
"subscriptionEvent": {
"type": "object",
"description": "Sent by the subscriber for one JSON message of a subscription; the relay writes message to the caller as one text frame.",
"required": [
"subscriptionId",
"message"
],
"properties": {
"subscriptionId": {
"type": "string",
"description": "The subscriptionId of the #subscribe."
},
"message": {
"type": "unknown",
"description": "The message, any JSON value; the caller gets its JSON text as is."
}
}
},
"subscriptionData": {
"type": "object",
"description": "Bytes of a subscription, in either direction: from the relay, one message the caller sent (text or binary); from the subscriber, one binary message for the caller (an event-stream frame, or a chunk of a tunnel's TCP stream). A caller that reads too slowly (4096 messages queued) is closed with code 1008 (consumer too slow).",
"required": [
"subscriptionId",
"data"
],
"properties": {
"subscriptionId": {
"type": "string",
"description": "The subscriptionId of the #subscribe."
},
"data": {
"type": "string",
"description": "The bytes, standard base64 with padding; data that does not decode is dropped."
}
}
},
"subscriptionClose": {
"type": "object",
"description": "Sent by the subscriber when a subscription ends (its upstream closed, its dial failed, its tunnel's TCP connection ended); the relay closes the caller's WebSocket with the code and reason. The relay handles a #subscriptionCancel from the subscriber the same way.",
"required": [
"subscriptionId"
],
"properties": {
"subscriptionId": {
"type": "string",
"description": "The subscriptionId of the #subscribe."
},
"code": {
"type": "integer",
"description": "The WebSocket close code for the caller; absent or 0 means 1000. A code outside 1000-1003, 1007-1014 and 3000-4999 is sent as 1000. The subscriber sends 1011 for a failed dial or handler."
},
"reason": {
"type": "string",
"description": "The close reason for the caller, cut to 123 bytes."
}
}
},
"subscriptionCancel": {
"type": "object",
"description": "Sent by the relay when the caller's WebSocket closed: the subscriber stops that subscription. The subscriber handles a #subscriptionClose from the relay the same way. When the subscriber itself goes away, the relay closes its callers with code 4004 (subscriber disconnected).",
"required": [
"subscriptionId"
],
"properties": {
"subscriptionId": {
"type": "string",
"description": "The subscriptionId of the #subscribe."
},
"reason": {
"type": "string",
"knownValues": [
"caller disconnected"
],
"description": "Why the relay cancelled it."
}
}
}
}
}