37 lines
1.7 KiB
Markdown
37 lines
1.7 KiB
Markdown
# 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.
|