Documentation
¶
Overview ¶
Package grantwire is what a command and the chassis agree on when the command exercises a run grant: the variables the command is handed, and the few lines of protocol the launcher (`txco sandbox`) speaks to the chassis over a Unix socket.
It is a leaf: the launcher is a small program that must start fast and import nothing of the server.
The protocol is one request and one response per connection, each a line of JSON. A request opens ONE sandbox, by name; the program never asks for a secret by name:
→ {"v":2,"token":"rg1.…","sandbox":"github"}
← {"ok":true,"env":{"GH_TOKEN":"<base64>"}}
← {"ok":false,"error":"refused"}
A refusal says nothing of why. The reason is in the trace of the tenant's `_grant` run, for whoever may read that; the program that asked may not.
Index ¶
Constants ¶
const ( EnvRun = "TXCO_RUN" // the run's name EnvToken = "TXCO_RUN_GRANT" // the token; the launcher presents it EnvSocket = "TXCO_GRANT_SOCK" // where the launcher reaches the chassis EnvBin = "TXCO_BIN" // the txco binary, for `"$TXCO_BIN" sandbox …` )
The variables a command is handed with its run grant.
const ( // Version is the protocol's. A chassis refuses one it does not speak. Version = 2 // MaxRequest bounds one request line; a token is about 350 bytes. MaxRequest = 8 << 10 // MaxResponse bounds one response line: a sandbox's values, base64, and // their frame. MaxResponse = 16 << 20 // MaxSocketPath is the longest path the chassis will listen on. A Unix // socket's address is a fixed field of the kernel's: 104 bytes on macOS, // 108 on Linux, the terminator included. MaxSocketPath = 100 )
const ( ErrorRefused = "refused" // the request was decided, and the answer is no ErrorBadRequest = "bad_request" // not a request this chassis understands )
The errors a response may carry.
Variables ¶
var ( // ErrRefused: the chassis decided, and the answer is no. ErrRefused = errors.New("refused") ErrUnavailable = errors.New("unavailable") )
Env is every one of them. The launcher removes them all from the environment of the program it starts.
Functions ¶
func Open ¶
Open asks the chassis listening on socket to open one sandbox and returns what it hands over, variable → value. The error is ErrRefused, or wraps ErrUnavailable with what went wrong between here and the chassis. The caller owns the values and should overwrite them once they are handed on.
Source Files