socialweb.computer

Request and provide VMs on an atproto compute market.

protocol: the atproto protocol of socialweb-computer

Files In This Tree

docwhat
README.mdthis index: NSID families, where each is documented, the end-to-end sequence
flow.mdone contract end to end, step by step, with real records: the story, S0 to S9, the failure branches, a real run
compute-contract-flow-map.mdthe owner's end-to-end map of the layers and the flow, from the lexicons to the guest transport
glossary.mdevery NSID on the wire, one line each, by namespace
release.mdsoftware.release.*: channels, versions, manifests; how install.sh and a bidder follow them
market.mdthe RFP flow: rfp, bid, accept, receipt, event, offering, heartbeat, relays, submit* XRPC, streams, selection
guest-events.mdcompute.events.vm.*, compute.events.guest.*, compute.guest.subscribeEvents, secrets, agent start, guest requester (R2)
lexicons-market.mdreference rows for every lexicon under com/publicdomainrelay/temp/ except cluster.* and badgeBlueKeys
infra.mdcomputer.socialweb.infra, ephemeralInfra, k8s.*, cluster.*: the deployment records and the gateway cluster API
identity.mdnetwork.attested.*, badgeBlueKeys, associations (plan 0036), did:key ingress, sign-in
policy.mdpolicy records (gha-lite workflows), the strongRefs an RFP attaches, tangled-vouch
outside.mdlexicons we use but do not own: sh.tangled.graph.vouch, chat.atirc.*, com.atproto.*, app.bsky.*, com.fedproxy.*, OAuth scopes per role

The Lexicon Reference

The lexicon files under lexicons/ are the one source of every record's and method's fields. The reference is generated from them: https://socialweb.computer/docs/lexicons/ (one page per NSID: type, key, fields, refs, errors, the raw schema and the docs pages that name it) and https://socialweb.computer/docs/xrpc/ (the XRPC methods). A docs page that shows a lexicon's fields includes the generated table (a [lexicon: <nsid>](https://socialweb.computer/docs/lexicons/<nsid>.html) line, rendered as the table on the site) and adds only what the code does with it:

rowmeaning
rkeyself, a deterministic key (named), tid, or any with the scheme the writer uses
written by / read bythe application role and the Go package
stepthe step of the end-to-end sequence where it appears

NSID Families

familyownerlexicon fileskinddoc
com.publicdomainrelay.temp.market.*uslexicons/com/publicdomainrelay/temp/market/records + XRPCmarket.md, lexicons-market.md
com.publicdomainrelay.temp.market.association, associationRequestussamerecordsflow: identity.md; rows: lexicons-market.md
com.publicdomainrelay.temp.compute.vmuslexicons/com/publicdomainrelay/temp/compute/vm.jsonrecord (RFP payload)market.md, lexicons-market.md
com.publicdomainrelay.temp.compute.events.*, compute.guest.subscribeEventsuslexicons/com/publicdomainrelay/temp/compute/event payload records, subscriptionguest-events.md
com.publicdomainrelay.temp.ingress.webRTCuslexicons/com/publicdomainrelay/temp/ingress/recordlexicons-market.md
com.publicdomainrelay.temp.cluster.*uslexicons/com/publicdomainrelay/temp/cluster/XRPC (gateway clusters)infra.md
com.publicdomainrelay.temp.badgeBlueKeysuslexicons/com/publicdomainrelay/temp/badgeBlueKeys.jsonrecord (key claim)identity.md
computer.socialweb.infra, computer.socialweb.ephemeralInfrauslexicons/computer/socialweb/records (deployments)infra.md
computer.socialweb.k8s.*uslexicons/computer/socialweb/k8s/XRPC (gateway k8s API)infra.md
network.attested.*not ours (a copy here)lexicons/network/attested/object, record, query; proof and verify are not written, served or called hereidentity.md
com.atproto.repo.strongRefatproto (vendored copy)lexicons/com/atproto/repo/strongRef.jsonobjectoutside.md
computer.socialweb.temp.policy.*, com.publicdomainrelay.temp.market.policies.denoWorkeruslexicons/computer/socialweb/temp/policy/, lexicons/com/publicdomainrelay/temp/market/policies/records (policy)policy.md
com.publicdomainrelay.temp.compute.config.wif.simple, compute.secrets.getSecretsuslexicons/com/publicdomainrelay/temp/compute/record (bid config), query (the guest's secrets)guest-events.md
com.publicdomainrelay.temp.auth.allowlist.rbacDid, com.publicdomainrelay.temp.keepalive.pinguslexicons/com/publicdomainrelay/temp/record (scope only), the ingress relay's keepaliveoutside.md
computer.socialweb.cicd.process.*uslexicons/computer/socialweb/cicd/process/XRPC (the guest agent's shell socket)-
sh.tangled.graph.vouchtanglednone hererecord (trust edge)outside.md, policy.md
chat.atirc.mint, chat.atirc.revokeatircatirc repoXRPCoutside.md
com.atproto.*, app.bsky.*atproto, BlueskyupstreamXRPC, recordsoutside.md
com.fedproxy.rbac, com.fedproxy.sshPublicKey, com.fedproxy.temp.xrpc.*uslexicons/com/fedproxy/records (workload roles, tunnel keys), XRPC (the did:key ingress relay)outside.md
software.release.*not ours (a copy here)lexicons/software/release/records (releases)release.md
computer.socialweb.ingress.*, computer.socialweb.peeruslexicons/computer/socialweb/records (webrtc ingress, peers)market.md, lexicons-market.md
link.ident.endorsementident.link (vendored)lexicons/link/ident/endorsement.jsonrecordidentity.md
com.fedfork.exec.ops.*uslexicons/com/fedfork/exec/ops/XRPC (read-only ops routes)../SYSTEM.md

One line per NSID: glossary.md.

NSIDs we own that have no lexicon file

NSIDwheredoc
com.fedfork.exec.binding, com.fedfork.exec.pinstheir lexicons are atlibs' lexicons/com/fedfork/exec/; hack/pinsrecords reads pins../ci-debug.md
com.fedfork.atprotoOauthQRinternal/atproto/oauthclient/qr.go QRNSID (client), did-key-associator/hono-backend/mod.ts (server); one NSID served as GET and POST, which no single lexicon method can describeglossary.md

Go Packages

packageholds
lexiconsthe lexicon JSON, embed.FS of com, computer, network
internal/lexgenthe generator: lexicon JSON -> Go record types, Validate, decodeRecord
internal/atproto/marketgenerated market, compute, ingress, badgeBlueKeys, network.attested.signature, strongRef types; NSID constants (nsid.go), stable rkeys
internal/atproto/infragenerated computer.socialweb.infra / ephemeralInfra types (nsid.go)
internal/atproto/oauthOAuth scope sets per role (scope.go)
internal/xrpcserverthe gateway XRPC server: cluster.*, computer.socialweb.k8s.*; validates against the embedded catalog
internal/atproto/pdsclientthe PDS client: getRecord, putRecord, createRecord, listRecords, getServiceAuth, subscribeRepos
internal/eventstreamthe market event streams and the one handler sink per role
internal/market/{requester,bidder,participant}the two sides of the RFP flow
internal/policyenginethe policy engine: executor, trust (vouches, associations), bundled gha-lite workflows

End-To-End Sequence

The steps below name every record in the order it is written. Other docs refer to them as S0 to S9. Each step with its real records: flow.md.

diagram
atircguest VMbidder repoBidderrequester repoRequester (CLI, page, iOS, gateway)user / operatoratircguest VMbidder repoBidderrequester repoRequester (CLI, page, iOS, gateway)user / operatorS0 sign in (OAuth, scopes per role)1S1 badgeBlueKeys claim, sh.tangled.graph.vouch2S2 computer.socialweb.infra (or ephemeralInfra) mirror3S3 policy record, compute.vm, market.rfp (signed)4discovery: getRecord market.offering + market.heartbeat at self5submitRfp (and RP-->>B: firehose market.rfp)6getRecord vm payload + attached policies7S4 compute.config.wif.simple, bids.free, market.bid8submitBid9S5 market.accept (+ market.association for a named subject)10submitAccept (capacity checked, reserved)11S6 market.receipt (payload = the compute.vm ref)12boot from cloud-init user_data13S7 market.event vm.hostKeys, vm.onNetwork14submitEvent15S8 market.event guest.* (secrets, agentStart, r2Start; for R2: market.association after its nonce)16chat.atirc.mint (service auth)17S9 chat.atirc.revoke18S9 market.event vm.delete19S9 market.event vm.terminated20S9 delete own contract records (rfp, vm, policy, accept, delete, rbac, association)21S9 infra status released / ended (record kept)22

S0: sign in

S1: trust

S2: declare the deployment

S3: policy, vm, rfp

S4: bid

S5: accept

S6: receipt

S7: boot and vm events

S8: guest events and atirc

S9: release

Records Policy (all families)

See Also