docs: add source-mapped server API reference

docs/api-routing-rooms.md

@@ -0,0 +1,92 @@
+---
+title: Routing and rooms API
+description: Source-mapped message routing and room management methods
+---
+
+# Routing and rooms API
+
+This page maps the routing surface at `symple-server` commit
+[`fbe14ed`](https://github.com/nilstate/symple-server/tree/fbe14edc843535ae5f5319f992b89ba1fe379142).
+
+## Incoming messages
+
+### `onRedisMessage(msg)`
+
+Routes Redis pub/sub messages to a peer address, a user room, or each room in
+an array. Invalid and unsupported payloads are ignored.
+
+[Source: lines 176-196](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L176-L196)
+
+### `onMessage(entry, msg)`
+
+Replaces the client-supplied `from` value with the authenticated peer address
+before routing, preventing sender spoofing.
+
+[Source: lines 310-314](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L310-L314)
+
+### `route(sender, msg)`
+
+Implements the `to` contract:
+
+- omitted: broadcast to all sender rooms;
+- `user|peerId`: direct send only when sender and recipient share a room;
+- `user`: broadcast to the user's room;
+- string array: broadcast to every named room.
+
+[Source: lines 390-420](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L390-L420)
+
+## Room membership
+
+### `onJoin(entry, room)`
+
+Adds a peer to a room only when dynamic rooms are enabled, then returns
+`join:ok`. Otherwise it sends an error without changing membership.
+
+[Source: lines 317-335](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L317-L335)
+
+### `onLeave(entry, room)`
+
+Removes membership from both the peer entry and room index, then returns
+`leave:ok`.
+
+[Source: lines 338-348](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L338-L348)
+
+### `sharesRoom(entryA, entryB)`
+
+Returns `true` as soon as two peers have one room in common. Direct-message
+authorization uses this check.
+
+[Source: lines 382-387](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L382-L387)
+
+### `addToRoom(room, peerId)`
+
+Creates a room set when needed and adds the peer ID.
+
+[Source: lines 470-475](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L470-L475)
+
+### `removeFromRoom(room, peerId)`
+
+Deletes a peer ID and removes the room itself when no members remain.
+
+[Source: lines 477-485](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L477-L485)
+
+## Outbound delivery
+
+### `broadcast(sender, msg)`
+
+Broadcasts to each room occupied by the sender while excluding that sender.
+
+[Source: lines 423-427](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L423-L427)
+
+### `broadcastToRoom(room, msg, excludeId)`
+
+Serializes once and sends to each connected room member except `excludeId`.
+
+[Source: lines 430-442](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L430-L442)
+
+### `sendTo(peerId, msg)`
+
+Sends to one connected peer and reports success as a boolean.
+
+[Source: lines 445-455](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L445-L455)
+

docs/api-server-lifecycle.md

@@ -0,0 +1,81 @@
+---
+title: Server lifecycle API
+description: Source-mapped lifecycle and transport methods in the Symple v4 server
+---
+
+# Server lifecycle API
+
+This reference is pinned to `symple-server` commit
+[`fbe14ed`](https://github.com/nilstate/symple-server/tree/fbe14edc843535ae5f5319f992b89ba1fe379142).
+Every method links to the exact source used for this page.
+
+## Construction and startup
+
+### `new Symple(config)`
+
+Creates the in-memory peer, room, and WebSocket lookup maps. The configuration
+accepts the HTTP port, Redis URL, SSL settings, session lifetime,
+authentication mode, and dynamic-room policy.
+
+[Source: `lib/symple.js` lines 25-31](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L25-L31)
+
+### `init()`
+
+Starts the HTTP transport, attaches the WebSocket server, and initializes the
+optional Redis clients.
+
+[Source: lines 33-38](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L33-L38)
+
+### `shutdown()`
+
+Broadcasts a shutdown event, closes connected sockets and transports, quits
+Redis clients, and clears all in-memory indexes.
+
+[Source: lines 40-60](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L40-L60)
+
+## Transport initialization
+
+### `initHTTP()`
+
+Creates an HTTP or HTTPS server once. `PORT` overrides `config.port`; HTTPS
+reads the configured key and certificate files.
+
+[Source: lines 63-76](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L63-L76)
+
+### `initWebSocket()`
+
+Attaches `WebSocketServer` to the HTTP server. A new connection must
+authenticate within ten seconds. After authentication, message types are
+dispatched to routing, room, leave, or close handlers.
+
+[Source: lines 79-145](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L79-L145)
+
+### `initRedis()`
+
+Creates the command and subscription clients when `config.redis` is set, then
+subscribes to `symple:broadcast` for server-side message injection.
+
+[Source: lines 148-173](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L148-L173)
+
+## Extension and error hooks
+
+### `onAuthorize(ws, peer)`
+
+Override this no-op hook to run application logic after a peer has been
+successfully registered.
+
+[Source: lines 458-461](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L458-L461)
+
+### `sendError(ws, status, message)`
+
+Sends a protocol error envelope and ignores a send failure caused by a socket
+that has already closed.
+
+[Source: lines 463-468](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L463-L468)
+
+### `onRedisError(err)`
+
+Reports a Redis client error to standard error.
+
+[Source: lines 488-490](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L488-L490)
+

docs/api-sessions-peer.md

@@ -0,0 +1,100 @@
+---
+title: Sessions and Peer API
+description: Source-mapped authentication, session, disconnect, and Peer model methods
+---
+
+# Sessions and Peer API
+
+The server and model references below are pinned to `symple-server` commit
+[`fbe14ed`](https://github.com/nilstate/symple-server/tree/fbe14edc843535ae5f5319f992b89ba1fe379142).
+
+## Authentication and sessions
+
+### `onAuth(ws, req, msg)`
+
+Validates the user, loads a Redis session when authentication is enabled,
+applies the optional asynchronous `authenticate(peer, auth)` hook, joins
+authorized rooms, registers the peer, sends `welcome`, and broadcasts online
+presence.
+
+[Source: lines 199-307](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L199-L307)
+
+### `getSession(token, fn)`
+
+Reads `symple:session:<token>` from Redis and returns a parsed object through
+the Node-style callback. Missing, malformed, and Redis-error cases are
+reported explicitly.
+
+[Source: lines 492-506](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L492-L506)
+
+### `touchSession(token, fn)`
+
+Extends a Redis session expiry from `sessionTTL`; a value of `-1` disables
+expiry updates.
+
+[Source: lines 509-518](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L509-L518)
+
+### `onDisconnect(ws)`
+
+Marks the peer offline, broadcasts final presence, removes all room
+memberships, and clears the peer and socket indexes.
+
+[Source: lines 351-379](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L351-L379)
+
+### `parseAddress(str)`
+
+Parses `user` or `user|peerId` into an address object.
+
+[Source: lines 521-529](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L521-L529)
+
+### `randomId()`
+
+Produces the non-cryptographic session identifier used for connected peers.
+
+[Source: lines 531-535](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/symple.js#L531-L535)
+
+## Peer model
+
+### `new Peer(data)`
+
+Creates a peer and copies the supplied session fields when present.
+
+[Source: `lib/peer.js` lines 13-17](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/peer.js#L13-L17)
+
+### `read(from)`
+
+Copies own enumerable properties from an input object onto the peer.
+
+[Source: lines 19-25](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/peer.js#L19-L25)
+
+### `write(to)`
+
+Copies the peer's own enumerable properties into a destination object.
+
+[Source: lines 27-33](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/peer.js#L27-L33)
+
+### `toPresence(p)`
+
+Builds a presence envelope, removes a string token from public peer data, and
+applies a valid display-name update.
+
+[Source: lines 35-52](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/peer.js#L35-L52)
+
+### `toPeer(p)`
+
+Serializes peer fields into a supplied or new object.
+
+[Source: lines 54-58](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/peer.js#L54-L58)
+
+### `address()`
+
+Returns the canonical `user|id` address.
+
+[Source: lines 60-62](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/peer.js#L60-L62)
+
+### `valid()`
+
+Accepts peers only when both `id` and `user` are truthy.
+
+[Source: lines 64-66](https://github.com/nilstate/symple-server/blob/fbe14edc843535ae5f5319f992b89ba1fe379142/lib/peer.js#L64-L66)
+

docs/sourcey.config.ts

@@ -10,7 +10,7 @@ export default defineConfig({
       dark: "#6d28d9",
     },
   },
-  repo: "https://github.com/nilstate/symple-server",
+  repo: "https://github.com/nilstate/symple-docs",
   editBranch: "main",
   editBasePath: "docs",
   navigation: {
@@ -30,7 +30,14 @@ export default defineConfig({
             },
             {
               group: "Server",
-              pages: ["server", "authentication", "scaling"],
+              pages: [
+                "server",
+                "authentication",
+                "scaling",
+                "api-server-lifecycle",
+                "api-routing-rooms",
+                "api-sessions-peer",
+              ],
             },
             {
               group: "Clients",
@@ -52,6 +59,7 @@ export default defineConfig({
   navbar: {
     links: [
       { type: "github", href: "https://github.com/nilstate/symple-server" },
+      { type: "link", label: "Docs source", href: "https://github.com/nilstate/symple-docs" },
       { type: "npm", href: "https://www.npmjs.com/package/symple-client" },
     ],
   },