Rust embed
Installation · Integration · Sockets · Messages · Provider · Embed
This console app embeds a URnetwork Device inside your own product on Windows, macOS and Linux. Your backend provisions a URnetwork client for each installation of your app and delivers its scoped client JWT; the app starts a Device with it, connects to the best available location and shows the status, the data used this month and the running total. The Device carries only the app's own traffic: it uses no VPN APIs, and what the app sends through it continues in the Sockets examples; the Messages examples run on a provider-capable Device of their own (Next). It follows the embed contract over the SDK's C ABI. Its embed core is a library that the Tauri embed app shares.
Files
| File | Purpose |
|---|---|
| src/main.rs | Commands, settings, stop signals and exit codes. |
| src/token.rs | fetch_: the token fetch, the one function to replace with your own sign-in. |
| src/config.rs | Loading the installation and the client JWT at start. |
| src/session.rs | The embedded Device over the C ABI: listeners, best available location, status, cap reads, stop. |
| src/status.rs | The status fields and their exact text rules. |
| src/caps.rs | The cap object and the app's own cap read with its client JWT. |
| src/state.rs | The private installation state directory. |
| src/http.rs, src/sdk_json.rs, src/id.rs | HTTPS with origin rules, the C ABI's JSON values, canonical ids. |
| src/self_test.rs, src/stand_in.rs, tests/self_test.rs | Credential-free self-test, with a loopback stand-in for the token server and the API; also run by cargo test. |
| src/lib.rs, Cargo.toml | The embed core library (urnetwork_) and the embed binary. |
| server/src/main.rs, server/Cargo.toml, server/Cargo.lock | The backend tool, server only: provision, caps, usage and removal. |
Build and self-test
Use Rust 1.85 or later (edition 2024). Cargo.toml requires the SDK crate as urnetwork-sdk = "0.0.1-dev.0"; select a release from the first one after sdk c638dfa8, which adds the client limit status, or use the local development patch below. The published crate embeds a checksum-verified native runtime for each supported platform when it builds, so the built embed needs nothing else at run time. From rust/embed, on macOS and Linux:
cargo build --release
cargo test
./target/release/embed --self-test
./target/release/embed --licenses > licenses.json
./target/release/embed --versionOn Windows, in PowerShell, the same cargo commands build target\release\embed.exe; run .\target\release\embed.exe --self-test. Linux builds need a glibc target: the SDK has no musl runtime.
Before the crate is published, build against a local SDK checkout. make -C sdk/rust stages a crate with the native runtime embedded in sdk/; pass it as a Cargo patch to every cargo command:
cargo build --release --config 'patch. crates-io. urnetwork-sdk.path= "/ absolute/ path/ to/ sdk/ rust/ dist/ project"'Or patch in the source crate sdk/rust and point URNETWORK_ at a C ABI library built in sdk/cgo from the same checkout (libURnetworkSdk., libURnetworkSdk.so or URnetworkSdk.dll) whenever the app runs:
cargo build --release --config 'patch. crates-io. urnetwork-sdk.path= "/ absolute/ path/ to/ sdk/ rust"'
export URNETWORK_ SDK_ LIBRARY= /absolute/ path/ to/ sdk/ cgo/ build/ darwin/ arm64/ libURnetworkSdk. dylib
./target/release/embed --licenses > licenses.json
./target/release/embed --version--self-test needs no credentials, no network and no native runtime. It checks the contract's byte, reset time, client limit and status line vectors and the order of the status rules, the data fields, the cap object, the C ABI JSON that the status reads, the client JWT's client_id claim, the token fetch and the cap read against a loopback stand-in (the request, saving client.jwt atomically, a mismatched answer refused, every answer mapped to its exit code), the cap read schedule, the state files (private permissions, atomic replacement, instance-id created once, a symlink refused), the configuration errors and the usage exit code. cargo test runs the same checks one by one, plus the C ABI callback tests. --version loads the native runtime and prints the SDK version.
Backend
Only your backend holds the root credential, as URNETWORK_: an API key for production, or a network JWT. An API key authenticates as your network exactly like the root JWT, with the same full-network scope (it is not narrower): create one with POST /account/ (called with a network JWT; the key, which begins urn_, is shown only in that answer), list them with GET /account/ and revoke one with POST /account/. Treat it like a production database password. To rotate, create a new key, deploy it, then remove the old one; remove a leaked key at once (contract).
Each installation that can run at the same time as another needs its own client: the platform keeps one resident connection per client, so two installations sharing one would keep displacing each other. The backend keys each client by user:, where the installation ID is the app's instance-id. Data caps belong to a client, so they apply per installation (contract).
With the token server. The Go token server in go/ is the reference backend: the app posts its instance-id with a demo session, and the server provisions or reissues the installation's client, puts new clients in their ACL group (isolated unless URNETWORK_ is default), applies default caps to them and answers the client JWT. Run it with your root credential and point the app at it (Configure the installation).
With the Rust backend tool. server/src/main.rs extends the integration allocator with the embed commands; it has the same settings, map format, key pattern, lock and response checks, and no SDK dependency. From rust/:
cargo build --locked
./ target/ debug/ urnetwork-embed-server --self-test
umask 077
mkdir -p /absolute/ path/ to/ private-service-state
chmod 700 /absolute/ path/ to/ private-service-state
export URNETWORK_ CLIENT_ MAP= '/ absolute/ path/ to/ private-service-state/ clients.json'
export URNETWORK_ DEFAULT_ ACL_ GROUP= isolated
export URNETWORK_ ROOT_ JWT= 'urn_ ...an-api-key-from-your-secret-store'
KEY= 'user: alice: 22222222-2222-2222-2222-222222222222' # the installation's instance-id
./ target/ debug/ urnetwork-embed-server provision "$KEY" /absolute/ path/ to/ private-service-state/ alice.jwt
./ target/ debug/ urnetwork-embed-server cap "$KEY" --monthly 10000000000
./ target/ debug/ urnetwork-embed-server usage "$KEY"
./ target/ debug/ urnetwork-embed-server usage-all
./ target/ debug/ urnetwork-embed-server acl "$KEY" default
./ target/ debug/ urnetwork-embed-server status| Command | Does |
|---|---|
provision <key> <client-jwt-file> | Reissues the key's client, or provisions a new one (and a new one when a reissue answers Client does not exist., after 30 days without connecting). Writes the client JWT to the file, private, and prints {"client_. |
cap <key> [--monthly <bytes>| | Posts only the given fields: an omitted option keeps the cap, null clears it, a byte count sets it. --reset-total starts a new running total. Prints the cap object. |
usage <key> | Prints the key's cap object. |
usage-all | Pages through every capped client of the network, one cap object per line. |
remove <key> | Removes the key's client and its mapping and prints {"removed": ...}. |
acl <key> default| | Sets the key's client's ACL group with POST /network/ and prints {"client_. |
On Windows, in PowerShell, set the variables with $env: and run .\target\debug\urnetwork-embed-server.exe. The tool exits 0 on success, 78 for a configuration or credential problem (missing settings, an invalid key or map, the root credential refused, the client limit) and 1 for any other failure, with one stderr line that never holds a secret. It refuses the token server's map, which has an extra pending_caps field, so the two never rewrite each other's map. New clients go into the ACL group that URNETWORK_ names: isolated when it is unset, so your users never see each other in your network's peer list, or default for an app that uses Messages. provision saves a new client's mapping with a pending_acl record, applies the group with POST /network/, and only then writes the client JWT; after a failure the record stays and the next provision applies the group. acl <key> default or acl <key> isolated moves a client later and prints {"client_. cap, usage, remove and acl exit 78 with no client is mapped for that key; run provision first for a key without a client, and a held map lock exits 1. On a server that predates a route the tool exits 1 with /network/, or <path> answered 404: the server predates the data-cap routes for the cap routes; set URNETWORK_ to provision on a server without ACL groups (contract). status prints your network's Embed state from GET /network/ as one line, embed enabled: yes | client limit: 5000 | active clients: 1234. Until the URnetwork team enables Embed for your network (an Embed plan), cap, usage, usage-all and acl exit 78 with embed not enabled: Embed isn't enabled for this network; see https://, and provision still writes the client JWT but keeps the default ACL group in pending_acl and prints embed not enabled: the client's defaults stay pending until Embed is enabled; see https:// on stderr; the next provision after Embed is enabled applies it (contract).
The same requests with curl:
API= https:// api. bringyour.com
curl -fsS -X POST "$API/ network/ auth-client" -H "Authorization: Bearer $URNETWORK_ROOT_JWT" \
-H 'Content-Type: application/json' --data '{"description": "embed client", "device_spec": "urnetwork-examples/ curl"}'
curl -fsS -X POST "$API/ network/ client-acl-group" -H "Authorization: Bearer $URNETWORK_ROOT_JWT" \
-H 'Content-Type: application/json' --data '{"client_id": "<client id>", "acl_group": "isolated"}'
curl -fsS -X POST "$API/ network/ client-data-cap" -H "Authorization: Bearer $URNETWORK_ROOT_JWT" \
-H 'Content-Type: application/json' --data '{"client_id": "<client id>", "monthly_byte_limit": 10000000000}'
curl -fsS "$API/ network/ client-data-cap?client_ id= <client id>" -H "Authorization: Bearer $URNETWORK_ROOT_JWT"A reissue posts the stored client_id with the same description and device spec; the contract covers the answers.
Pause and remove. A cap of 0 pauses an installation (cap "$KEY" --monthly 0; a monthly cap of 0 stays paused when the month rolls over); set the cap back to resume. remove "$KEY" removes the client: the platform refuses its client JWT at the next connection. To keep a user out, your service also refuses their sign-in, or the next sign-in provisions a new client.
The client limit. A network can have 100 top-level clients by default: active clients without a source_ that are not provider installs; a client stops counting when it is removed or after 30 days without connecting. Provisioning past the limit is refused with Client limit exceeded. (the tool prints client limit reached: ... and exits 78). An Embed plan raises your network's limit: request one on the Services page.
Package
The urnetwork-sdk crate downloads a version-pinned, checksum-verified native runtime when it builds and embeds it in the executable, on Windows, macOS and Linux (glibc), so the app ships as one binary with no separate library. Pin the crate with cargo add urnetwork-sdk@<version>; SDK_ names a prepopulated offline cache for builds without network access.
The SDK is licensed under the Mozilla Public License 2.0: your app's own code can stay proprietary, and changes to the SDK's own source files are shared under the MPL. Publish the SDK's licenses and data attributions with your app: ./ prints them as JSON for this OS (GetLicenses, C ABI urnet_, with no network).
The app keeps client.jwt in its private state directory, protected by the operating system's user isolation; a production app may also encrypt it with the platform's secret store (the Keychain, DPAPI or the Secret Service). The client JWT is a bearer secret: never print, log or back it up. The Device uses no VPN APIs, so no VPN entitlement applies, but your app's privacy disclosures still must say that it routes some of its users' traffic through URnetwork; the SDK ships no privacy manifest of its own.
Configure the installation
All installation state is in one private directory named by URNETWORK_, an absolute path, private to the user (0700 on macOS and Linux). Use a directory inside your app's data, for example ~/ on macOS, ${XDG_ on Linux and %LOCALAPPDATA%\<your app>\embed on Windows. The app creates instance-id there on first run and rewrites client.jwt whenever the SDK refreshes the token; the SDK keeps its bounded log files in logs/.
With a token server, set both URNETWORK_ (an HTTPS origin, or explicit loopback HTTP for local testing) and URNETWORK_ (the demo session from the token server's session file, standing in for your sign-in). The app fetches its client JWT on every start, which reissues the client:
umask 077
export URNETWORK_ EMBED_ STATE_ DIR= "$HOME/ Library/ Application Support/ com. example.app/ embed"
mkdir -p "$URNETWORK_ EMBED_ STATE_ DIR" && chmod 700 "$URNETWORK_ EMBED_ STATE_ DIR"
export URNETWORK_ TOKEN_ SERVER_ URL= 'http:// 127.0.0.1: 8790'
export URNETWORK_ DEMO_ SESSION= 'the-demo-session-token-from-your-session-file'$env: URNETWORK_ EMBED_ STATE_ DIR = "$env: LOCALAPPDATA\com. example.app\embed"
New-Item -ItemType Directory -Force -Path $env: URNETWORK_ EMBED_ STATE_ DIR | Out-Null
$env: URNETWORK_ TOKEN_ SERVER_ URL = 'http://127.0.0.1:8790'
$env: URNETWORK_ DEMO_ SESSION = 'the-demo-session-token-from-your-session-file'Without a token server, the app uses the client.jwt already in the directory, as the backend tool's provision wrote it: run the app once to create instance-id (it then stops with exit 78, as there is no client.jwt yet), provision user: into "$URNETWORK_, and start it again. URNETWORK_ (optional, an HTTPS origin) names the API for the cap reads.
Run
./target/release/embedOn Windows, .\target\release\embed.exe. The app prints the client and installation IDs, then a status line whenever a field changes and otherwise once a minute:
embed client 11111111-1111-1111-1111-111111111111, installation 22222222-2222-2222-2222-222222222222
status: connected | data this month: 1.2 GB of 5.0 GB | data total: no cap| Field | Meaning |
|---|---|
| Status | connecting until the window has a provider added, then connected; client limit, retry at HH:MM UTC while the platform holds this client off; paused at a cap of 0; data cap reached, resets YYYY-MM-DD HH:MM UTC at the monthly cap, or data cap reached at the running total. |
| Data this month | <used> of <limit> for the monthly cap, in decimal units; no cap without one; checking before the first read; unavailable if that read failed. While Embed isn't enabled for your network, the cap read answers Embed isn't enabled for this network. and both data fields read unavailable (contract). |
| Data total | The same for the running-total cap. |
client limit means the platform disconnected this client because your network reached its plan's concurrent client limit; the SDK retries by itself after about 15 to 20 minutes, at the time the status shows. At a data cap the client gets no new transfer contracts: the monthly cap resets at 00:00 UTC on the first of the month, and the running total until your backend raises, clears or resets it. Usage lags live traffic and can pass a cap by up to the size of the contracts still open. The app reads its caps with its client JWT at start, every 5 minutes and within 5 seconds of a contract change.
Ctrl-C or SIGTERM stops the Device and exits 0. The app exits 78 for a configuration or credential problem that a restart does not fix (missing or invalid state, a network JWT, a credential the server rejected, or a token server answer of 401 or 409) and 1 for any other failure, including any other token server answer. The commands are run (the default), --self-test, --licenses and --version; any other argument is a usage error (78).
Next
The Device carries your app's own traffic. Continue with the same identity, one program at a time:
export URNETWORK_ CLIENT_ JWT= "$(cat "$URNETWORK_ EMBED_ STATE_ DIR/ client.jwt")"
export URNETWORK_ INSTANCE_ ID= "$(cat "$URNETWORK_ EMBED_ STATE_ DIR/ instance-id")"$env:URNETWORK_CLIENT_JWT = (Get-Content "$env: URNETWORK_ EMBED_ STATE_ DIR\client.jwt").Trim()
$env: URNETWORK_ INSTANCE_ ID = (Get-Content "$env: URNETWORK_ EMBED_ STATE_ DIR\instance-id").Trim()- Sockets: TCP, UDP and HTTP clients through the Device; libraries that need an operating system socket use the loopback proxy (networking matrix).
- Messages: Messages exchange the URMS text and ACK protocol with other clients of your network, but not on the embed Device, which does not provide. A Messages program starts its own provider-capable Device for the installation, and that Device provides to your network: your network's other clients can route traffic through the installation, so ask your users first. Messages also need the client in the
defaultACL group: provision withURNETWORK_, or move the client with the backend tool'sDEFAULT_ ACL_ GROUP= default acl <key> default. Anisolatedclient, the examples' default, never appears in your network's peer list; adefaultclient appears there while the network has 100 or fewer recently active top-level clients that are not isolated, and your app decides what of it to show.