ADR 0003: Current Net API State

Status

Accepted

Date

2026-06-07

Context

/apis/net is the current networking abstraction in this repository.

It wraps modem messages with packet metadata and uses /apis/eventloop for listeners and request/response flows. It is useful for today's basic routed messages and RPC-like requests, but it is not a final protocol design.

Decision

Keep using /apis/net for simple program and server messaging.

Document the current behavior as the baseline, without over-designing the future protocol before real needs appear.

Current State

Default routing channel is 10.
Ping channel is 9.
Packets include sourceId, sourceLabel, routerId, destId, and message.
Main convenience APIs include send, listen, sendRequest, sendMultipleRequests, listenRequest, createEvent, createRequest, and openChannel (alias open). Listening on a non-default channel requires openChannel first.
sendRequest and sendMultipleRequests run a private event loop, default to a 0.5s timeout, and return ok, result, packet (or ok, results, packets for the multi variant).
Router behavior currently lives separately in /programs/router.lua. A router must be running on the network — otherwise non-router senders produce packets with routerId = nil and isPacketOk drops them on receive, so cross-machine messages silently fail.

Consequences

Use /apis/net for current basic messaging needs.
Keep duplicated well-known channel constants in sync while they remain duplicated.
Future ADRs can replace or refine this one if the network protocol gains discovery, retries, schemas, versioning, auth, or a different routing model.

1.7 KiB Raw Blame History