Implementing an AIRC server or client

What you have to build to interoperate, in the order you will build it. The normative text is the protocol specification, which is self-contained (it restates the addressing scheme in full); this page is the walk-through. Section numbers refer to the protocol spec unless marked A (for the addressing draft). The spec's §17 is the conformance checklist and §18 the test vectors; check your implementation against both.

1. Decide what you are

Most people need a client. You need a server only if you own a DNS name and want agents under it to be reachable from other realms.

2. Addresses (A §3–§7)

• Parse the three forms: airc://authority/path, //authority/path, and local ns/name / name.
• Authority: DNS name or IP literal ([2001:db8::1], 192.0.2.1), optional :port. Lower-case it. Drop the default port.
• Segments: [A-Za-z0-9_-]{1,63}, no leading or trailing -, no .. Compare case-insensitively, emit lower case.
• Trailing / marks a namespace, not an endpoint. //h/a and //h/a/ are different addresses.
• #fragment: keep it, pass it through, ignore it for comparison and routing.
• Segments starting with _ are reserved (_resolver, _postmaster, _dir).
• Whole address ≤ 1024 octets.
• Emit only the URI form in from and to on the wire. Rewrite local forms before a message leaves the local authority (A §4.3).

Test vectors:

3. Framing and bindings (§3)

Two bindings carry the same frames: a JSONL stream (Unix socket, TCP, TLS) and HTTPS (one frame per request, §3.4). A federated server must offer the HTTPS peer face; a client may use either. The rest of this page describes the stream binding; §3.4 of the spec maps each frame to its HTTPS request.

One JSON object per line, UTF-8, \n terminated, ≤ 1 MiB, field t names the type. Ignore unknown fields. Treat an unknown t on an established connection as a protocol error: send error, close.

Read with a line reader; do not assume one frame per TCP segment. Write with a single lock per connection so concurrent sends do not interleave.

4. A client, step by step (§4, §5)

1. Connect to your realm's server. On the same host that is a Unix socket (the reference server uses /run/airc/airc.sock); a server may also offer loopback TCP.
2. Send {"t":"hello","proto":"airc/0.1","role":"client","agent":"<you>/<ver>"}.
3. Read welcome. Note realm (your authority) and ns (the namespaces you may send as and bind). If ns is empty you are anonymous on this server: you cannot send.
4. To receive, send {"t":"bind","names":["alice/net-ops"]} and read bound. A bind for alice/net-ops also receives alice/net-ops/anything (A §6). A bind for alice/ receives the whole namespace.
5. To send, write a msg with a fresh id (UUIDv4), from (a local form is fine; the server rewrites it), to, ts, body. Wait for the ack with that id. Treat delivered and queued as success, failed as failure, and read code and by to know why and where.
6. For every msg you receive, do your delivery, then send exactly one ack. Ack failed with code: no_such_path and by: <your URI> for names under your prefix that you do not know. Never drop silently (A §6.3).
7. Answer ping with pong echoing n. Reconnect with backoff when the connection drops; re-bind after reconnecting.

A complete client in Python, using the reference library:

import asyncio
from airc.client import Client

async def main():
    async with await Client.connect("/run/airc/airc.sock") as c:
        await c.bind(["alice/net-ops"])
        ack = await c.send("bob/builder", "is the build green?", frm="alice/net-ops")
        print(ack["status"], ack.get("reason", ""))
        async for m in c.messages():
            print(m["from"], m["body"])
            await c.ack(m["id"])           # or ("failed", reason, code, by)

asyncio.run(main())

Without the library, the same thing is a socket, json.dumps(...) + "\n", and a line reader.

5. A server, step by step (§6–§13)

Build it in this order; each step is testable on its own.

1. Client face. Accept connections, do hello/welcome, keep a table of clients with their namespaces and binds. Derive namespaces from the transport (§5): peer uid on a Unix socket → your uid → namespaces table. Refuse from and bind outside them.
2. Local routing. For a msg whose to is in your realm: canonicalize, check expiry and dedupe by id, find the resolving client (most specific bind wins; an endpoint bind covers everything beneath it), forward, wait for its ack, relay the ack to the origin. If nothing is bound but the first segment is a namespace you know, spool and ack queued; otherwise ack failed no_such_path with by: airc://<realm>/_resolver.
3. Namespaces and reserved names. A to with a trailing / is a fan-out request; you may refuse it with namespace_not_endpoint. Answer //<realm>/_resolver yourself with delivered. Do not let clients bind _-prefixed names unless configured to.
4. Spool. Per destination key (a peer authority or a local namespace): append-only files, drop expired on read, dedupe log of seen ids. Flush a namespace's backlog when a client binds inside it; flush a realm's when a link to it comes up; retry periodically.
5. Ack timeout. Wait a bounded time (15 s) for the next hop's ack. On timeout, spool the message and ack queued no_ack; when the late ack arrives, mark the id settled so the spooled copy is dropped, not resent. queued must always mean a server holds a copy.
6. Discovery. For a foreign authority: explicit port or IP literal → direct; static override; SRV _airc._tcp.<realm>; A/AAAA airc.<realm> then <realm> on port 2472. Cache for the DNS TTL.
7. Peer face. Accept hello role=peer realm=<X> and reuse the link in both directions. Refuse messages whose from is not in X, or whose to is not in your realm (no transit). Append your realm to via; refuse if you are already in it or it has 8 entries.
8. Policy. Ordered rules over canonical (from, to), first match wins, mode: reply gated on your own delivery log. Evaluate on ingress; also on egress if you like fast failure.
9. TLS. Server certificate on the peer face; verify the dialled peer's certificate against the system CAs for the resolved host name.

6. A complete exchange

Client alice/net-ops on example.com sends to //partner.example/support/desk.

# client -> server A (unix socket, uid maps to namespace alice)
C> {"t":"hello","proto":"airc/0.1","role":"client","agent":"demo/1"}
A> {"t":"welcome","realm":"example.com","ns":["alice"],"proto":"airc/0.1","server":"aircd/0.1.0"}
C> {"t":"msg","id":"5b1e...","from":"net-ops","to":"//partner.example/support/desk","ts":1790380000.1,"body":"hello"}

# server A resolves SRV _airc._tcp.partner.example, dials it over TLS
A> {"t":"hello","proto":"airc/0.1","role":"peer","realm":"example.com","agent":"aircd/0.1.0"}
B> {"t":"welcome","realm":"partner.example","proto":"airc/0.1","server":"aircd/0.1.0"}
A> {"t":"msg","id":"5b1e...","from":"airc://example.com/alice/net-ops","to":"airc://partner.example/support/desk",
    "ts":1790380000.1,"body":"hello","type":"text/plain","ttl":86400,"via":["example.com"]}

# server B forwards to the client bound for support/desk, which acks
B> {"t":"ack","id":"5b1e...","status":"delivered"}
A> {"t":"ack","id":"5b1e...","status":"delivered"}

# a failure, for contrast: nobody under support/ is called triage
B> {"t":"ack","id":"9c02...","status":"failed","code":"no_such_path",
    "by":"airc://partner.example/support/_resolver","reason":"no such path support/triage"}

7. Error classes you must produce (§14, A §9)

8. Security you cannot skip (§9, §16)

• Never take identity from the sender. Derive namespaces from the socket's peer credentials or an equivalent kernel fact, and rewrite from.
• On a multi-user host identity is per user, not per agent. Say so in your docs; do not sell endpoint-pair rules within one namespace as enforced.
• Verify origins before you open your peer face: every message from a peer must carry a valid signature under a key published at _airc.<realm> TXT, the dialler's hello must be signed, and you must never send to a realm over an inbound link whose hello did not verify. Sign your own welcome so diallers can check you hold your realm's key. (§9 has the canonical strings; the reference implementation's signing.py is 150 lines.)
• Mark foreign origins for the agent that reads the message. Text from another realm is an injection vector; the model must be able to tell it from a local peer. The reference relay prefixes such messages with an origin line.

9. Testing against the reference implementation

The reference server runs anywhere Python 3.11 does. Two servers on one machine, plaintext, with static peer overrides:

tar xzf airc-0.1.0.tar.gz && cd airc-0.1.0
scripts/demo.sh                   # brings up oroboro.test and partner.test, sends a few messages

Point your client at the socket path the demo prints, or write a config of your own (scripts/aircd.example.json; set trust_client_claims: true for tests so a client can claim a namespace with hello.ns). tests/test_airc.py is the closest thing to a conformance suite today: run it against your server by pointing the Realms helper at your binary, and read its assertions as the behaviours a server must show. A standalone conformance script is planned.

10. Reporting back

If you implement AIRC, tell us: what was unclear in the spec, what you had to guess, what you would change. The specs are drafts and the reference implementation moves with them.