@factoidal/core 0.28.0 → 0.30.0

package/xmpp/inpage.mjs

@@ -0,0 +1,197 @@
+// factoidal/xmpp/inpage.mjs — the Lean XMPP server with no network: it
+// runs in the page (or a worker, or Node) beside the code that talks to it,
+// and each connection is a pair of in-order message channels.
+//
+//   import { loadEngine } from '@factoidal/core/browser'
+//   import { openInPageXmppServer, inPageWebSocket } from '@factoidal/core/xmpp/inpage'
+//   const server = await openInPageXmppServer({ engine: await loadEngine(),
+//     domain: 'foafos.local', mucDomain: 'rooms.foafos.local',
+//     accounts: [{ username: 'shell', password }] })
+//   const link = server.connect()            // { send(message), onmessage, close() }
+//   const WS = inPageWebSocket(server)       // a WebSocket-shaped class for
+//   new WS('xmpp-inpage:', 'xmpp')           //   Strophe.js and other RFC 7395 clients
+//
+// A message is one RFC 7395 message (https://www.rfc-editor.org/rfc/rfc7395):
+// `<open/>` and `<close/>` in the framing namespace, then one complete
+// element each. The engine's message carrier (`xmppMsgOpen`, `xmppMsgFeed`,
+// `xmppMsgDeliver`, `xmppMsgClose`; Wasm/Ops/XmppSession.lean) makes every
+// protocol decision; this file only moves messages and performs the routes
+// (router.mjs, shared with the Node host). No Node or browser API beyond
+// `crypto.getRandomValues` and `queueMicrotask`.
+//
+// There is no socket, so there is no Origin to check: whoever holds the
+// server object can connect, and the accounts' passwords are what the
+// engine checks (SCRAM-SHA-256). The host page decides which code gets it.
+
+import { createXmppRouter } from './router.mjs'
+
+/** Unpredictable values for the stream id and the SCRAM server nonce
+ *  (RFC 6120 section 4.7.3, RFC 5802 section 5.1); the engine asks the host. */
+function randomToken (bytes = 18) {
+  const b = new Uint8Array(bytes)
+  globalThis.crypto.getRandomValues(b)
+  let s = ''
+  for (const x of b) s += String.fromCharCode(x)
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+/**
+ * @param {object} options
+ * @param {object} options.engine a loaded engine handle (`loadEngine()`)
+ * @param {string} [options.domain] default `localhost`
+ * @param {Array<{username: string, password: string}>} [options.accounts]
+ * @param {string} [options.mucDomain] XEP-0045 rooms (L4Factoidal/XMPP/Muc.lean)
+ * @param {string} [options.mixDomain] XEP-0369 channels (L4Factoidal/XMPP/Mix.lean)
+ * @param {string} [options.gc3Domain] GC3 prototype groups (L4Factoidal/XMPP/Gc3.lean)
+ * @param {Function} [options.onError]
+ */
+export async function openInPageXmppServer (options = {}) {
+  const engine = options.engine
+  if (!engine || typeof engine.call !== 'function') throw new Error('openInPageXmppServer: options.engine is required')
+  const onError = typeof options.onError === 'function' ? options.onError : (e) => console.error(`xmpp-inpage: ${e.message}`)
+  const config = {}
+  for (const k of ['domain', 'mucDomain', 'mixDomain', 'gc3Domain', 'saltB64']) {
+    if (typeof options[k] === 'string') config[k] = options[k]
+  }
+  if (Array.isArray(options.accounts)) config.accounts = options.accounts
+  if (typeof options.iterationCount === 'number') config.iterationCount = options.iterationCount
+  const opened = engine.call('xmppOpen', [JSON.stringify(config)])
+  if (typeof opened.handle !== 'string') throw new Error('xmppOpen answered with no handle')
+  const handle = opened.handle
+  const router = createXmppRouter({ onError })
+  let closed = false
+
+  function connect () {
+    if (closed) throw new Error('the in-page XMPP server is closed')
+    const got = engine.call('xmppMsgOpen', [handle, JSON.stringify({ streamId: randomToken(), nonce: randomToken() })])
+    if (typeof got.handle !== 'string') throw new Error('xmppMsgOpen answered with no handle (an engine without the message carrier?)')
+    const session = got.handle
+    let open = true
+    // Messages to the client go out in order, never inside an engine call.
+    const emit = (msgs) => {
+      for (const m of msgs) {
+        queueMicrotask(() => {
+          if (typeof link.onmessage === 'function') {
+            try { link.onmessage(m) } catch (error) { onError(error) }
+          }
+        })
+      }
+    }
+    const end = () => {
+      if (!open) return
+      open = false
+      router.connections.delete(c)
+      let answer
+      try { answer = engine.call('xmppMsgClose', [session]) } catch (error) { onError(error); answer = { send: [], routeFull: [] } }
+      for (const r of answer.routeFull || []) router.routeFull(null, r.to, r.text, null)
+      emit(answer.send || [])
+      queueMicrotask(() => { if (typeof link.onclose === 'function') link.onclose() })
+    }
+    const c = {
+      bare: null,
+      full: null,
+      deliver (text) {
+        if (!open) return false
+        const answer = engine.call('xmppMsgDeliver', [session, text])
+        if (answer.delivered === true) { emit(answer.send); return true }
+        return false
+      }
+    }
+    router.connections.add(c)
+    const link = {
+      onmessage: null,
+      onclose: null,
+      get open () { return open },
+      /** One whole RFC 7395 message from the client. */
+      send (message) {
+        if (!open) throw new Error('the in-page XMPP connection is closed')
+        let answer
+        try { answer = engine.call('xmppMsgFeed', [session, String(message)]) } catch (error) { onError(error); end(); return }
+        emit(answer.send || [])
+        router.apply(c, answer)
+        if (answer.close === true) end()
+      },
+      close: end
+    }
+    return link
+  }
+
+  return {
+    engine,
+    handle,
+    domain: typeof opened.domain === 'string' ? opened.domain : (config.domain || 'localhost'),
+    mucDomain: config.mucDomain || null,
+    connect,
+    /** The live connections' `{bare, full}` pairs. */
+    sessions () { return Array.from(router.connections, (c) => ({ bare: c.bare, full: c.full })) },
+    close () {
+      if (closed) return
+      closed = true
+      for (const c of Array.from(router.connections)) router.connections.delete(c)
+      try { engine.call('xmppClose', [handle]) } catch (_error) { /* already gone */ }
+    }
+  }
+}
+
+/**
+ * A WebSocket-shaped class whose instances are connections to `server`, so
+ * an RFC 7395 client written for `WebSocket` (Strophe.js, the foafos XmppWs
+ * client) runs unchanged. The URL is not used; the subprotocol is `xmpp`.
+ */
+export function inPageWebSocket (server) {
+  return class InPageWebSocket {
+    static CONNECTING = 0
+    static OPEN = 1
+    static CLOSING = 2
+    static CLOSED = 3
+    constructor (url, protocols) {
+      this.url = String(url)
+      this.protocol = 'xmpp'
+      this.readyState = 0
+      this.binaryType = 'blob'
+      this.bufferedAmount = 0
+      this.extensions = ''
+      this.onopen = this.onmessage = this.onclose = this.onerror = null
+      this._listeners = { open: [], message: [], close: [], error: [] }
+      const wanted = Array.isArray(protocols) ? protocols : (protocols === undefined ? [] : [protocols])
+      queueMicrotask(() => {
+        if (wanted.length > 0 && !wanted.includes('xmpp')) { this._fail(); return }
+        try { this._link = server.connect() } catch (_error) { this._fail(); return }
+        this._link.onmessage = (data) => this._fire('message', { type: 'message', data, target: this })
+        this._link.onclose = () => this._closed(1000)
+        this.readyState = 1
+        this._fire('open', { type: 'open', target: this })
+      })
+    }
+    addEventListener (type, fn) { this._listeners[type]?.push(fn) }
+    removeEventListener (type, fn) {
+      const l = this._listeners[type]
+      if (l) { const i = l.indexOf(fn); if (i >= 0) l.splice(i, 1) }
+    }
+    dispatchEvent (event) { this._fire(event.type, event); return true }
+    send (data) {
+      if (this.readyState !== 1) throw new Error('InvalidStateError: the connection is not open')
+      this._link.send(String(data))
+    }
+    close (code = 1000) {
+      if (this.readyState >= 2) return
+      this.readyState = 2
+      this._link?.close()
+      if (!this._link) this._closed(code)
+    }
+    _fail () {
+      this._fire('error', { type: 'error', target: this })
+      this._closed(1006)
+    }
+    _closed (code) {
+      if (this.readyState === 3) return
+      this.readyState = 3
+      this._fire('close', { type: 'close', code, reason: '', wasClean: code === 1000, target: this })
+    }
+    _fire (type, event) {
+      const prop = this['on' + type]
+      if (typeof prop === 'function') prop.call(this, event)
+      for (const fn of [...(this._listeners[type] || [])]) fn.call(this, event)
+    }
+  }
+}

package/xmpp/router.mjs

@@ -0,0 +1,96 @@
+// factoidal/xmpp/router.mjs — the routing table of an XMPP host, with no
+// transport: the Node host (`server.mjs`, TCP, TLS, WebSocket) and the
+// in-page host (`inpage.mjs`, whole messages over a MessagePort or a
+// function call) share it. No Node or browser API is used here.
+//
+// A connection is any object with `bare`, `full` (the last values the
+// engine reported, or null) and `deliver(text) → boolean` (hand it a stanza
+// another session routed to it; false when its session refused). The engine
+// decides where every stanza goes (`route`, `routeFull` of a feed answer);
+// this file only finds the connections and calls `deliver`.
+
+/**
+ * @param {object} [options]
+ * @param {Function} [options.onError]
+ * @param {number} [options.pendingLimit] stanzas kept per bare JID for the
+ *   race where a session closed between the engine's decision and the
+ *   delivery (default 100)
+ */
+export function createXmppRouter (options = {}) {
+  const onError = typeof options.onError === 'function' ? options.onError : () => {}
+  const pendingLimit = typeof options.pendingLimit === 'number' ? options.pendingLimit : 100
+  /** Every live connection. */
+  const connections = new Set()
+  /** bare JID → stanzas routed to it while no session was bound. */
+  const pending = new Map()
+
+  function boundTo (bare) {
+    const found = []
+    for (const c of connections) if (c.full !== null && c.bare === bare) found.push(c)
+    return found
+  }
+
+  function hold (bare, text) {
+    if (!pending.has(bare)) pending.set(bare, [])
+    const q = pending.get(bare)
+    if (q.length < pendingLimit) q.push(text)
+    else onError(new Error(`dropped a stanza for ${bare}: the host fallback queue is full`))
+  }
+
+  /**
+   * Deliver one stanza to every session bound to `bare`. The engine holds
+   * stanzas for accounts with no bound session (L4Factoidal/XMPP/Held.lean,
+   * bounded; issue 1235), so a route reaches here only for a bound account.
+   * `pending` covers the race where that session closed between the
+   * engine's decision and this delivery; it is bounded too.
+   */
+  function routeStanza (bare, text) {
+    const targets = boundTo(bare)
+    if (targets.length === 0) { hold(bare, text); return }
+    for (const t of targets) {
+      let delivered = false
+      try { delivered = t.deliver(text) } catch (error) { onError(error); continue }
+      if (!delivered) hold(bare, text)
+    }
+  }
+
+  /**
+   * `Out.routeFull`: deliver to the ONE session bound to `full`, now. With no
+   * such session (or one that refuses), deliver the engine's bounce, if it
+   * gave one, back to the sending session. Never held (RFC 6120 section
+   * 10.5.3.2; https://github.com/danbri/factoidal/issues/1234).
+   */
+  function routeFull (sender, full, text, bounce) {
+    for (const t of connections) {
+      if (t.full !== full) continue
+      try { if (t.deliver(text)) return } catch (error) { onError(error) }
+    }
+    if (typeof bounce === 'string' && sender !== null) {
+      try { sender.deliver(bounce) } catch (error) { onError(error) }
+    }
+  }
+
+  /** A session just bound: hand it what was waiting. */
+  function flushPending (c) {
+    const queue = pending.get(c.bare)
+    if (!queue || queue.length === 0) return
+    pending.delete(c.bare)
+    for (const text of queue) routeStanza(c.bare, text)
+  }
+
+  /**
+   * The routing part of one feed answer: the session's JIDs as the engine
+   * reports them, then `route` and `routeFull`, then what waited for a
+   * session that has just bound.
+   */
+  function apply (c, answer) {
+    const wasBound = c.full !== null
+    c.bare = typeof answer.bare === 'string' ? answer.bare : null
+    c.full = typeof answer.full === 'string' ? answer.full : null
+    for (const r of answer.route || []) routeStanza(r.to, r.text)
+    for (const r of answer.routeFull || []) routeFull(c, r.to, r.text, r.bounce)
+    if (!wasBound && c.full !== null) flushPending(c)
+  }
+
+  return { connections, pending, boundTo, routeStanza, routeFull, flushPending, apply }
+}