@irtio/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 irtio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import { AnySchema, RoleOf, ServerCallProxy, SchemaRpc, BroadcastProxy, State, OwnableKeys, DeepReadonly, SchemaDefs, InstanceOf, Implementations, ServerRpcs } from '@irtio/schema';
+
+/**
+ * `@irtio/server` — what `irtio/room.ts` imports. `defineRoom(schema, config)` validates the
+ * config, fills defaults, and returns a plain `RoomDefinition` the runtime loads from the bundle.
+ * No behaviour lives here; everything is types plus definition-time checks.
+ */
+
+/** `'all'` (everyone but the sender for relayed messages), a client id, or a role. */
+type MessageTarget = 'all' | string | {
+    readonly role: string;
+};
+interface ClientInfo {
+    readonly clientId: string;
+    readonly role: string;
+    readonly name: string;
+    readonly connected: boolean;
+}
+type TimerHandle = number;
+interface Room<S extends AnySchema = AnySchema> {
+    readonly id: string;
+    /** Shareable URL (`?room=<id>`). */
+    readonly link: string;
+    readonly tick: number;
+    /** Server ms; prefer over `Date.now()` (replayable). */
+    readonly now: number;
+    /** Built-in presence, ordered by join. */
+    readonly clients: readonly ClientInfo[];
+    /** Seeded, recorded for replay. */
+    random(): number;
+    send(target: MessageTarget, bytes: Uint8Array): void;
+    setRole(clientId: string, role: RoleOf<S> & string): void;
+    kick(clientId: string, reason?: string): void;
+    close(reason?: string): void;
+    /** Event mode: ask to hibernate now. */
+    sleep(): void;
+    log(...args: unknown[]): void;
+    /** Live-only timers (cancelled on hibernation). */
+    setTimeout(ms: number, fn: () => void): TimerHandle;
+    setInterval(ms: number, fn: () => void): TimerHandle;
+    clearTimeout(handle: TimerHandle): void;
+    clearInterval(handle: TimerHandle): void;
+    /** Server → client RPC (Promise; 5 s default timeout; rejects on disconnect). */
+    call(clientId: string): ServerCallProxy<SchemaRpc<S>>;
+    /** Server → client void RPCs to every connected client. */
+    readonly broadcast: BroadcastProxy<SchemaRpc<S>>;
+}
+interface Ctx<S extends AnySchema = AnySchema> {
+    readonly clientId: string;
+    readonly role: RoleOf<S> & string;
+    readonly name: string;
+    /** Server tick this join/call/write is applied at. */
+    readonly tick: number;
+    /** Joins only: a resumed session. */
+    readonly reconnecting: boolean;
+    readonly room: Room<S>;
+}
+type LeaveReason = 'left' | 'timeout' | 'kicked' | 'closed';
+type RoomMode = 'tick' | 'event';
+type Instance<S extends AnySchema, K extends keyof SchemaDefs<S>> = InstanceOf<SchemaDefs<S>[K]>;
+/** Per-entity owner-write validators: return `next` (accept), `prev` (reject), or a clamped object. */
+type Validators<S extends AnySchema> = {
+    readonly [K in OwnableKeys<S>]?: (prev: DeepReadonly<Instance<S, K>>, next: DeepReadonly<Instance<S, K>>, ctx: Ctx<S>) => Instance<S, K> | DeepReadonly<Instance<S, K>>;
+};
+type RpcImplementations<S extends AnySchema> = Implementations<ServerRpcs<SchemaRpc<S>>, State<S>, Ctx<S>>;
+type RpcConfig<S extends AnySchema> = keyof ServerRpcs<SchemaRpc<S>> extends never ? {
+    readonly rpc?: RpcImplementations<S>;
+} : {
+    readonly rpc: RpcImplementations<S>;
+};
+interface RoomConfigBase<S extends AnySchema> {
+    /** `'tick'` (fixed-rate loop; default) or `'event'` (apply on arrival, hibernates). */
+    readonly mode?: RoomMode;
+    /** Tick mode only; default 20. */
+    readonly tickRate?: number;
+    /** Event mode: hibernate after this long with no frames; default 30 000. */
+    readonly idleMs?: number;
+    /** Reconnection grace window; default 30 000. */
+    readonly reconnectGraceMs?: number;
+    /** Default 64. */
+    readonly maxClients?: number;
+    onCreate?(state: State<S>, room: Room<S>): void;
+    onJoin?(state: State<S>, ctx: Ctx<S>): void;
+    onLeave?(state: State<S>, ctx: Ctx<S>, reason: LeaveReason): void;
+    onSleep?(state: State<S>, room: Room<S>): void;
+    onWake?(state: State<S>, room: Room<S>): void;
+    /** Tick mode: fixed `dt` in seconds; queued writes/calls already applied. */
+    tick?(state: State<S>, dt: number, room: Room<S>): void;
+    readonly validate?: Validators<S>;
+    /** Implements the built-in `requestOwnership` RPC. Default: grant if unowned. */
+    onOwnershipRequest?(state: State<S>, entity: OwnableKeys<S> & string, id: string, ctx: Ctx<S>): boolean;
+    /** Raw relay messages; return `false` to drop. */
+    onMessage?(state: State<S>, from: string, target: MessageTarget, bytes: Uint8Array, ctx: Ctx<S>): boolean | undefined | void;
+}
+type RoomConfig<S extends AnySchema> = RoomConfigBase<S> & RpcConfig<S>;
+/** Config with defaults filled and `rpc` always present. */
+interface ResolvedRoomConfig<S extends AnySchema> extends RoomConfigBase<S> {
+    readonly mode: RoomMode;
+    readonly tickRate: number;
+    readonly idleMs: number;
+    readonly reconnectGraceMs: number;
+    readonly maxClients: number;
+    readonly rpc: RpcImplementations<S>;
+}
+interface RoomDefinition<S extends AnySchema = AnySchema> {
+    readonly kind: 'irtio-room';
+    readonly version: 1;
+    readonly schema: S;
+    readonly config: ResolvedRoomConfig<S>;
+}
+declare const ROOM_DEFINITION_VERSION: 1;
+declare const DEFAULTS: {
+    readonly mode: "tick";
+    readonly tickRate: 20;
+    readonly idleMs: 30000;
+    readonly reconnectGraceMs: 30000;
+    readonly maxClients: 64;
+};
+/**
+ * Validates a room config and returns the definition the runtime loads. Throws on: unknown
+ * mode, bad tickRate, `tick` missing in tick mode or present in event mode, `async`/generator
+ * handlers (handlers are synchronous), and `rpc` keys that don't match the schema's
+ * server RPCs exactly.
+ */
+declare function defineRoom<S extends AnySchema>(schema: S, config: RoomConfig<S>): RoomDefinition<S>;
+/** Type guard for what a bundle's default export should be. */
+declare function isRoomDefinition(v: unknown): v is RoomDefinition;
+
+export { type ClientInfo, type Ctx, DEFAULTS, type LeaveReason, type MessageTarget, ROOM_DEFINITION_VERSION, type ResolvedRoomConfig, type Room, type RoomConfig, type RoomConfigBase, type RoomDefinition, type RoomMode, type RpcImplementations, type TimerHandle, type Validators, defineRoom, isRoomDefinition };

package/dist/index.js

@@ -0,0 +1,99 @@
+// src/index.ts
+var ROOM_DEFINITION_VERSION = 1;
+var DEFAULTS = {
+  mode: "tick",
+  tickRate: 20,
+  idleMs: 3e4,
+  reconnectGraceMs: 3e4,
+  maxClients: 64
+};
+var HANDLER_KEYS = [
+  "onCreate",
+  "onJoin",
+  "onLeave",
+  "onSleep",
+  "onWake",
+  "tick",
+  "onOwnershipRequest",
+  "onMessage"
+];
+function defineRoom(schema, config) {
+  if (!schema || typeof schema !== "object" || !Array.isArray(schema.collections)) {
+    throw new Error("defineRoom: first argument must be a schema from defineSchema()");
+  }
+  const mode = config.mode ?? DEFAULTS.mode;
+  if (mode !== "tick" && mode !== "event") {
+    throw new Error(`defineRoom: mode must be 'tick' or 'event', got ${JSON.stringify(mode)}`);
+  }
+  const tickRate = config.tickRate ?? DEFAULTS.tickRate;
+  if (!Number.isInteger(tickRate) || tickRate < 1 || tickRate > 240) {
+    throw new Error(`defineRoom: tickRate must be an integer in 1..240, got ${String(tickRate)}`);
+  }
+  for (const k of ["idleMs", "reconnectGraceMs", "maxClients"]) {
+    const v = config[k];
+    if (v !== void 0 && (!Number.isFinite(v) || v < 0)) {
+      throw new Error(`defineRoom: ${k} must be a non-negative number, got ${String(v)}`);
+    }
+  }
+  if (mode === "tick" && typeof config.tick !== "function") {
+    throw new Error("defineRoom: tick(state, dt, room) is required in 'tick' mode");
+  }
+  if (mode === "event" && config.tick !== void 0) {
+    throw new Error("defineRoom: tick() is not allowed in 'event' mode (use RPCs and timers)");
+  }
+  for (const k of HANDLER_KEYS) assertSyncHandler(config[k], k);
+  const rpc = config.rpc ?? {};
+  const validate = config.validate ?? {};
+  for (const [k, fn] of Object.entries(rpc)) assertSyncHandler(fn, `rpc.${k}`);
+  for (const [k, fn] of Object.entries(validate)) assertSyncHandler(fn, `validate.${k}`);
+  const expected = schema.rpcs.filter((r) => r.direction === "server").map((r) => r.name).sort();
+  const given = Object.keys(rpc).sort();
+  const missing = expected.filter((n) => !given.includes(n));
+  const extra = given.filter((n) => !expected.includes(n));
+  if (missing.length || extra.length) {
+    const parts = [];
+    if (missing.length) parts.push(`missing implementations: ${missing.join(", ")}`);
+    if (extra.length) parts.push(`unknown rpc keys: ${extra.join(", ")}`);
+    throw new Error(`defineRoom: rpc ${parts.join("; ")}`);
+  }
+  for (const [k] of Object.entries(validate)) {
+    const c = schema.collections.find((x) => x.name === k);
+    if (!c || c.kind !== "entity" || c.serverOwned) {
+      throw new Error(`defineRoom: validate.${k} must name an instance-owned entity collection`);
+    }
+  }
+  const resolved = {
+    ...config,
+    mode,
+    tickRate,
+    idleMs: config.idleMs ?? DEFAULTS.idleMs,
+    reconnectGraceMs: config.reconnectGraceMs ?? DEFAULTS.reconnectGraceMs,
+    maxClients: config.maxClients ?? DEFAULTS.maxClients,
+    rpc
+  };
+  return Object.freeze({
+    kind: "irtio-room",
+    version: ROOM_DEFINITION_VERSION,
+    schema,
+    config: Object.freeze(resolved)
+  });
+}
+function assertSyncHandler(fn, name) {
+  if (fn === void 0) return;
+  if (typeof fn !== "function") throw new Error(`defineRoom: ${name} must be a function`);
+  const ctor = fn.constructor?.name;
+  if (ctor === "AsyncFunction" || ctor === "AsyncGeneratorFunction" || ctor === "GeneratorFunction") {
+    throw new Error(
+      `defineRoom: ${name} is ${ctor}; handlers are synchronous (no await inside a tick) \u2014 use RPCs, timers, or room.call() continuations instead`
+    );
+  }
+}
+function isRoomDefinition(v) {
+  return typeof v === "object" && v !== null && v.kind === "irtio-room" && v.version === ROOM_DEFINITION_VERSION;
+}
+export {
+  DEFAULTS,
+  ROOM_DEFINITION_VERSION,
+  defineRoom,
+  isRoomDefinition
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@irtio/server",
+  "version": "0.1.0",
+  "description": "irtio room-file API: defineRoom, handler and ctx types",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@irtio/schema": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}