Utilities & cross-slice
What sits at the SDK's top level, beside Backbone and Deed rather than inside either, and Edge, which calls your other slices.
Signatures
// Outbound HTTP, egress-gated.
HTTPRequest(method, url string, headers map[string]string, body []byte) (*HTTPResponse, error)
HTTPRequestWithTimeout(method, url string, headers map[string]string, body []byte, timeout time.Duration) (*HTTPResponse, error)
type HTTPResponse struct { Status int; Body []byte } // no headers, status and body only
// drift.Edge.Slice(name): a slice this one links under edge.links.
// drift.Slice(name) is the deprecated spelling of the same call.
// An unlinked name errors before any network I/O.
Get(path string) (*HTTPResponse, error)
Post(path string, body any) (*HTTPResponse, error) // JSON-encodes body
Request(method, path string, headers map[string]string, body []byte) (*HTTPResponse, error)
CallerSlice(req Request) string · Env(key string) string · Log(msg string)Outbound HTTP
The default timeout is 30 seconds; HTTPRequestWithTimeout takes your own. What a request may reach is the slice's egress posture. Private address space is unreachable whatever your Driftfile says: RFC-1918, link-local (including the cloud metadata endpoint) and CGNAT are excepted from the slice's outbound rule, and the slice runtime refuses a connection to them as well, except port 53 of the slice's own nameservers, which stays open so a hostname can resolve.
A blocked or failed request does not surface the same way in every language. Go, Python, Node.js and Ruby treat it as a failure: Go returns an error, and the other three raise or throw. PHP and Rust instead answer with a status of 0 and an empty or explanatory body, no exception involved, so a caller there has to check the status before trusting the rest of the response.
Go tells an egress refusal apart from a broken remote.
HTTPRequest wraps an allowlist refusal in *EgressDeniedError, matchable with errors.As, so a handler can answer one differently from a remote that is merely down. The match is best-effort, on the same connection refused that a refused dial and a genuinely dead host both produce, so treat it as a debugging aid rather than a proof.var ee *drift.EgressDeniedError
if errors.As(err, &ee) {
return 502, "external API not allowlisted", map[string]string{"host": ee.Host}
}Rust: outbound HTTPS needs the tls feature.
ureq with default-features = false, so it is pure Rust and cross-compiles with rustup alone. In that build an https:// URL returns (0, "drift-sdk: outbound HTTPS needs the \"tls\" feature …") without a request ever leaving the process, so check the status and don't assume the call happened. Enabling features = ["tls"] pulls ring (C and assembly), and deploys then need a C cross-toolchain such as zig.Cross-slice: Edge.Slice
Edge.Slice(name) calls another slice you own that this slice links to. Declare the link in the Driftfile under edge.links:
edge {
links = ["billing"]
}resp, err := drift.Edge.Slice("billing").Post("/api/charge", body)Each language spells it its own way:
- Call
drift.Edge.Slice("billing")- Deprecated spelling
drift.Slice
- Call
drift.edge.slice("billing")- Deprecated spelling
drift.slice
- Call
drift.edge.slice("billing")- Deprecated spelling
drift.slice
- Call
Drift::Edge.slice("billing")- Deprecated spelling
Drift.slice
- Call
\Drift\Edge\slice('billing')- Deprecated spelling
\Drift\slice
- Call
drift_sdk::edge::slice("billing")- Deprecated spelling
drift_sdk::slice
The old spelling returns the same client, so existing code keeps working.
A call to a slice that is not linked fails before any network I/O, with an error that names the fix:
drift: slice "billing" is not linked: declare it under edge.links in the DriftfileYour function never learns where the linked slice lives. It is handed a local address on its own slice, and the slice runtime relays each call to the linked slice inside Drift: method, path, query, headers and body, with the answer streamed back, so an SSE or WebSocket reply works through it. No internal name or address reaches your code, including in errors: a linked slice that cannot be reached answers 502 naming the link and nothing else.
The call carries this slice's identity in X-Drift-Slice only when the runtime supplies one, and a header of your own by that name never replaces it. CallerSlice(req) reads that header on the far end. Any caller can write it, so treat it as a label for logging and routing: it authorises nothing, and the linked slice authenticates a call like any other.
Links covers the relay end to end, the commands, and every refusal a linked call can meet. Cross-slice calling is deliberately not under Backbone, because it is inter-slice networking. Not to be confused with Deed.Link, which enrolls a device for one identity.
Environment
Env exists in all six SDKs and returns an empty string for a missing key. Reaching past it for the language's own accessor changes that: Python's os.environ[key] raises KeyError rather than returning "". For secrets specifically, use Secret.Get rather than either, because it resolves the value whichever way the runtime delivered it.