@weft-js/realtime-socketio 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+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/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @weft-js/realtime-socketio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Early release (0.1.0).** APIs will change between minor versions.
+
+Cursors through a Socket.IO relay you run, with tickets the room signs.
+
+```bash
+npm install @weft-js/realtime-socketio
+```

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@weft-js/realtime-socketio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "@weft-js/realtime-socketio: cursors through a Socket.IO relay you run, with tickets the room signs",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./relay": "./src/relay.ts",
+    "./plugin": "./plugin.mjs"
+  },
+  "dependencies": {
+    "socket.io-client": "4.8.4"
+  },
+  "peerDependencies": {
+    "@weft-js/start": "^0.1.0",
+    "@weft-js/core": "^0.1.0",
+    "@weft-js/multiplayer": "^0.1.0",
+    "socket.io": "^4.8.0"
+  },
+  "peerDependenciesMeta": {
+    "socket.io": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "src",
+    "plugin.mjs",
+    "plugin.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.d.mts

@@ -0,0 +1,5 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+declare const plugin: (options?: Record<string, unknown>) => PluginInstance<unknown>
+/** `socketio()` for `weft.config.ts`: puts the relay on the record of what the app reaches. A page passes the transport to `presence`. */
+export default plugin

package/plugin.mjs

@@ -0,0 +1,14 @@
+// socketio() for weft.config.ts: no slot, since a page passes the transport to `presence`.
+import { definePlugin } from '@weft-js/core/plugin'
+
+export const socketio = definePlugin({
+  name: '@weft-js/realtime-socketio',
+  version: '0.1.0',
+  weft: '*',
+  permissions: { net: ['browser:socketio-relay'] },
+  contribute: () => ({
+    agents: { title: 'Peer transport (Socket.IO)', text: '`presence(conn, { transport: socketio({ url }) })` sends cursors through your relay. Run `relay(io, { secret })` from `@weft-js/realtime-socketio/relay` there, and pass `ticket: socketioTicket({ secret })`, from the same file, to `multiplayer()`. For migrations: with no relay already running, leave it out.' },
+  }),
+})
+
+export default socketio

package/src/index.ts

@@ -0,0 +1,37 @@
+// Cursors through a Socket.IO relay you already run, for apps moving off one. The relay (`./relay`) checks the ticket the
+// room signed, and stamps every frame with the ticket's subject, so a client can't speak as anyone else.
+
+import { createRoot, derived, state, untrack } from '@weft-js/core'
+import { io, type Socket } from 'socket.io-client'
+import type { PeerLink, PeerRoom, PeerTransport } from '@weft-js/multiplayer'
+
+/** Options of `socketio()`. */
+export interface SocketIoOptions {
+  /** The relay. */
+  url: string
+  path?: string
+}
+
+/** A peer transport through a Socket.IO relay, for `presence(conn, { transport })`. */
+export function socketio({ url, path }: SocketIoOptions): PeerTransport {
+  return {
+    name: 'socketio',
+    open(room: PeerRoom): PeerLink {
+      return createRoot(dispose => {
+        const joined = state(false)
+        const socket: Socket = io(url, { ...(path === undefined ? {} : { path }), auth: { ticket: room.ticket }, transports: ['websocket'] })
+        socket.on('weft:ok', () => { joined.value = true })
+        socket.on('disconnect', () => { joined.value = false })
+        socket.on('weft:f', (from: unknown, text: unknown) => { if (typeof from === 'string' && typeof text === 'string') room.receive(from, text) })
+        return {
+          up: derived(() => joined.value && room.peers.value.length > 0),
+          send: text => { if (untrack(() => joined.value)) socket.volatile.emit('weft:f', text) },
+          close() {
+            socket.disconnect()
+            dispose()
+          },
+        }
+      })
+    },
+  }
+}

package/src/relay.ts

@@ -0,0 +1,37 @@
+// The relay's half, for a Socket.IO server you run: `relay(io, { secret })`. A connection without a good ticket is refused,
+// and a frame is fanned out with the ticket's subject as its sender.
+
+import type { Server, Socket } from 'socket.io'
+import { roomId, signTicket, verifyTicket } from '@weft-js/multiplayer/server'
+
+const FRAME = 1024
+
+/** Refuses a connection without a good ticket, and fans out each frame to its room under the ticket's subject. */
+export function relay(io: Server, { secret }: { secret: string }) {
+  const admit = async (socket: Socket, next: (error?: Error) => void) => {
+    const claims = await verifyTicket(socket.handshake.auth?.ticket, secret)
+    if (!claims?.sub || !claims.room) return next(new Error('bad ticket'))
+    socket.data = { peer: claims.sub, room: claims.room }
+    next()
+  }
+  io.use((socket: Socket, next) => void admit(socket, next))
+  io.on('connection', async (socket: Socket) => {
+    await socket.join(socket.data.room)
+    socket.emit('weft:ok')
+    socket.on('weft:f', (text: unknown) => {
+      if (typeof text === 'string' && text.length <= FRAME) socket.to(socket.data.room).volatile.emit('weft:f', socket.data.peer, text)
+    })
+  })
+}
+
+/** Options of `socketioTicket()`. */
+export interface TicketOptions {
+  /** Shared with the relay. */
+  secret: string
+  /** Seconds a ticket opens a connection. Default 3600. */
+  ttl?: number
+}
+
+/** For `multiplayer({ ticket })`: a signed claim of who this connection is and which room it may enter. */
+export const socketioTicket = ({ secret, ttl = 3600 }: TicketOptions) => async ({ id, params }: { id: string; params: unknown }) =>
+  signTicket({ sub: id, room: await roomId(params), exp: Math.floor(Date.now() / 1000) + ttl }, secret)