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.
const EntryList = "list"
EntryList is the Request.Entry that asks only which files a sandbox serves: nothing is released.
const Header = "Txco-Run-Grant"
Header is where the run grant's token travels on the network: the one the capability inlet reads (chassis/processor RunGrantHeader).
const SandboxPath = "/v1/sandbox/"
SandboxPath is the route a program on another machine opens a sandbox at, on its parent's web head: POST /v1/sandbox/<name>, the token in Header, the body {"entry": …}. The answer is a Response.
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 ¶
Types ¶
type Opened ¶ added in v0.2.51
Opened is what an open hands over: the values, and the files the sandbox serves (paths only).
func Open ¶
Open asks the chassis listening on socket to open one sandbox and returns what it hands over: variable (or file:<path>) → value, and the files it serves. 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.
type Request ¶
type Request struct {
V int `json:"v"`
Token string `json:"token"`
Sandbox string `json:"sandbox"`
Entry string `json:"entry,omitempty"`
}
Request is one ask: open a sandbox. Entry is what of it: "" its variables (to start a program); `file:<path>` one file it serves; `dotenv:<path>` its variables for its dotenv file (chassis/sandbox ParseEntry).
type Response ¶
type Response struct {
OK bool `json:"ok"`
Env map[string]string `json:"env,omitempty"` // variable (or file:<path>) → base64 (standard, padded)
Serve []string `json:"serve,omitempty"` // file:<path> and dotenv:<path>: what the sandbox serves as files
Error string `json:"error,omitempty"`
}
Response is the answer.
Source Files