matrix-nodejs-homeserver 0.2.0 → 0.3.1

package/README.md

@@ -5,7 +5,7 @@ tied to any HTTP framework, database, auth system or deployment shape. You can u
 it for a demo on SQLite, embed it in a monolith next to your existing users, or run
 it as a horizontally scaled chat backend that replaces Slack or Teams.
 
-- Node.js **26+**. TypeScript with only erasable syntax (`erasableSyntaxOnly`); one runtime dependency, [zod](https://zod.dev), for request validation.
+- Node.js **26+**. TypeScript with only erasable syntax (`erasableSyntaxOnly`), and no runtime dependencies ([zod](https://zod.dev), used for request validation, is bundled).
 - Client-Server API, Server-Server API (federation), end-to-end encryption, sliding sync, VoIP/MatrixRTC and push
 - Runs on `node:http`, Express, Fastify, Hono or any fetch runtime
 - Stores data in SQLite, PostgreSQL, MySQL, memory or your own adapter
@@ -139,8 +139,10 @@ createHomeserver({
 
 ## Federation
 
-Federation is on by default and needs no configuration beyond a reachable port
-8448, or `.well-known/matrix/server` delegation. The implementation includes:
+Federation is **off by default**, so a server only joins the Matrix network on purpose.
+Turn it on with `federation: { enabled: true }`. It then needs no configuration beyond a
+reachable port 8448, or `.well-known/matrix/server` delegation (`federationAddress`). The
+implementation includes:
 
 - Server discovery (`.well-known` and SRV) and signed requests
 - A persistent outbound queue with retries
@@ -155,7 +157,8 @@ Federation is on by default and needs no configuration beyond a reachable port
 federation: { enabled: true, allowedServers: ["partner.org"], blockedServers: ["spam.example"] },
 ```
 
-Set `federation: { enabled: false }` for a private deployment.
+Without federation, local users can only talk to each other: federation endpoints answer
+`M_UNRECOGNIZED`, and remote users, rooms and media cannot be reached.
 
 ## VoIP and MatrixRTC
 
@@ -302,9 +305,14 @@ await hs.admin.createUser("alice", { password: "…", admin: true });
 await hs.admin.createRegistrationToken({ usesAllowed: 10 });
 await hs.admin.deactivateUser("@spammer:example.com");
 await hs.admin.deleteRoom(roomId, { purge: true });
-await hs.admin.sendServerNotice("@alice:example.com", { msgtype: "m.text", body: "Maintenance tonight" });
+await hs.admin.sendServerNotice("@alice:example.com", { msgtype: M.TEXT, body: "Maintenance tonight" });
 ```
 
+`M` (exported from the package) holds the Matrix identifiers as one readonly object:
+`M.ROOM.MEMBER` is `"m.room.member"`, `M.LOGIN.PASSWORD` is `"m.login.password"`.
+`UNSTABLE` does the same for unstable and vendor identifiers:
+`UNSTABLE.ORG.MATRIX.CROSS_SIGNING_RESET` is `"org.matrix.cross_signing_reset"`.
+
 The same operations are available over HTTP at Synapse-compatible `/_synapse/admin/…`
 paths (server admins only), so existing tools keep working.
 
@@ -319,7 +327,7 @@ paths (server admins only), so existing tools keep working.
 | `audit` | `{ enabled, database, sink, actions, retentionDays }`. Disabled by default. |
 | `publicBaseUrl` | Advertised via `/.well-known/matrix/client`. Required for SSO. |
 | `oauth`, `sso` | Delegated OAuth or upstream OIDC SSO. |
-| `federation` | `{ enabled, verifyTls, allowedServers, blockedServers }` |
+| `federation` | `{ enabled, verifyTls, allowedServers, blockedServers, fasterJoins }`. Off unless `enabled: true`. |
 | `rtc` | `{ turn, transports }` |
 | `delayedEvents` | `{ maxDelayMs, maxPerUser }` |
 | `rateLimits` | `false`, or `{ limiter, rules }`. In-memory token buckets by default. Plug in a shared limiter when running a cluster. |
@@ -363,12 +371,26 @@ npm run build                    # tsdown → dist/ (what the published package
 node examples/node-http.ts       # development runs the TypeScript sources directly (type stripping)
 ```
 
+Endpoints are procedures (`src/http/procedure.ts`): a route declares what it needs and a
+handler, and the procedure checks the request in a fixed order (authentication, rate limit,
+body, then the response) before and after the handler runs:
+
+```ts
+r.client("POST", "/rooms/:roomId/invite", procedure({
+  auth: "user",                 // ctx.session (or "optional", "none")
+  rateLimit: "invite",
+  input: body({ user_id: lenient(z.string()), reason: lenient(z.string()) }), // ctx.input
+  handler: async (ctx) => { /* ctx.hs, ctx.session, ctx.input, ctx.params */ },
+}));
+```
+
 Inside `src`, modules import each other through the package's
 [subpath imports](https://nodejs.org/api/packages.html#subpath-imports): `#core/errors.ts` is
 `src/core/errors.ts`. The build turns them back into relative imports.
 
 Node does not strip types from files inside `node_modules`, so the package ships `dist/`,
-built by tsdown: one `.js` and one `.d.ts` per source module. `npm pack`, `npm publish` and
+built by tsdown: one `.js` and one `.d.ts` per source module, with zod bundled under
+`dist/vendor/`. `npm pack`, `npm publish` and
 installs from GitHub build it through the `prepare` script. Recent npm versions ask you to
 approve install scripts of git dependencies (`npm install-scripts approve`).