Build a carrier driver
A carrier driver connects the platform to a cellular carrier’s API: the
platform calls it for what it needs from the carrier (the calls are the
carrier-driver kind’s, below), and the driver answers with the carrier’s own
API, over pz.http. It is an extension module like a gateway package’s
adapter (abi.md), and is built, tested and released the same way.
pulzr-pkg new carrier acme-carriercd acme-carrierpulzr-pkg build && pulzr-pkg testWhat it may reach
Section titled “What it may reach”driver.json holds the module object, and declares everything the driver
needs from the platform:
"driver": { "runtime": "wasm", "module": "driver.wasm", "sha256": "...", "imports": ["http", "state"], "http": {"hosts": ["api.example.com"]}, "credentials": {"type": "object", "required": ["api_key"], "properties": {"api_key": {"type": "string", "title": "API key", "writeOnly": true}}}}http.hosts: the only hosts it reaches, HTTPS only.credentials: a JSON Schema of the form an organization’s admin fills in when installing the driver (writeOnlyorformat: passwordmarks a secret). A request names a field as{{credential.api_key}}(in a header or the body, never the URL), or{{basic:user:password}}for HTTP Basic, and the platform fills it in: the driver never holds a secret, and one echoed in a response is replaced before the driver reads it.Request::bearer("api_key")writes the usual header.state, for what it must keep between calls: an OAuth token for its lifetime ishost::state_set("token", token.as_bytes(), expires_in).- Fleets:
host::http_allmakes up to 128 requests at once; aGETcan be.cached(seconds), and an answer’sinvalidatedrops what a change made stale.
The carrier-driver kind’s events (its calls) and its answers are defined by
the platform’s connectivity service, which runs drivers; they arrive in your
module as Event::Other and go back in an
Answer’s extra members. Each call is one
organization’s: a driver instance never sees another organization’s calls,
state or credentials.
Testing
Section titled “Testing”pulzr-pkg test runs tests/*.jsonl through the platform’s host. A test can
give its install a credential ("credentials": {"api": "test-key"}); requests
in tests reach the real network only for the declared hosts, so prefer
recorded answers in your own tests of the parsing logic (plain Rust tests of
your functions), and keep tests/*.jsonl for the calls’ shapes.