@reddb-io/client 1.15.0 → 1.16.0

package/README.md

@@ -147,6 +147,14 @@ The client follows the SDK Helper Spec for the shared JS/TS surface:
 | `grpcs://`     | gRPC over TLS                 | 55555         |
 | `http://`      | HTTP JSON                     | 5000         |
 | `https://`     | HTTPS JSON                    | 55555         |
+| `ws://`        | RedWire over WebSocket        | 80           |
+| `wss://`       | RedWire over WebSocket + TLS  | 443          |
+| `red+ws://`    | RedWire over WebSocket        | 80           |
+| `red+wss://`   | RedWire over WebSocket + TLS  | 443          |
+
+Browser bundles cannot open raw TCP, so use `wss://host` (or `ws://host`
+for plaintext development origins) when connecting directly from browser
+JavaScript.
 
 ## Rejected URI schemes
 

package/index.browser.d.ts

@@ -13,8 +13,9 @@
  *   - It omits `splitNdjson()` (a `node:stream` `Transform`), which has no
  *     browser counterpart.
  *
- * `connect()` reaches `http(s)://` and `red+wss://` (RedWire-over-binary-
- * WebSocket, #937) from a browser; `grpc(s)://`, `red(s)://`, and `pg`
+ * `connect()` reaches `http(s)://`, `ws(s)://`, and `red+ws(s)://`
+ * (RedWire-over-binary-WebSocket, #937) from a browser; `grpc(s)://`,
+ * `red(s)://`, and `pg`
  * throw `RedDBError` with code `'BROWSER_TRANSPORT_UNSUPPORTED'`, and
  * embedded URIs throw `EmbeddedNotSupported`.
  */
@@ -422,8 +423,8 @@ export class RedDB {
 /**
  * Connect to a remote RedDB instance from a browser.
  *
- * `http://host:port`, `https://host:port`, and `red+wss://host:port`
- * (RedWire-over-binary-WebSocket, #937) are reachable from a browser
+ * `http://host:port`, `https://host:port`, `ws(s)://host:port`, and
+ * `red+ws(s)://host:port` (RedWire-over-binary-WebSocket, #937) are reachable from a browser
  * sandbox. `grpc(s)://`, `red(s)://`, and `pg` throw `RedDBError` with code
  * `'BROWSER_TRANSPORT_UNSUPPORTED'`. Embedded URIs (`memory://`, `memory:`,
  * `file:///path`, `red:///`, `red://:memory[:]`) throw `EmbeddedNotSupported`.
@@ -437,9 +438,10 @@ export function login(
 ): Promise<LoginResult>
 
 export interface ParsedUri {
-  kind: 'embedded' | 'http' | 'https' | 'red' | 'reds' | 'redwss' | 'grpc' | 'grpcs' | 'pg'
+  kind: 'embedded' | 'http' | 'https' | 'red' | 'reds' | 'redws' | 'redwss' | 'grpc' | 'grpcs' | 'pg'
   host?: string
   port?: number
+  tls?: boolean
   path?: string
   username?: string
   password?: string

package/index.d.ts

@@ -443,9 +443,10 @@ export function login(
 ): Promise<LoginResult>
 
 export interface ParsedUri {
-  kind: 'embedded' | 'http' | 'https' | 'red' | 'reds' | 'redwss' | 'grpc' | 'grpcs' | 'pg'
+  kind: 'embedded' | 'http' | 'https' | 'red' | 'reds' | 'redws' | 'redwss' | 'grpc' | 'grpcs' | 'pg'
   host?: string
   port?: number
+  tls?: boolean
   path?: string
   username?: string
   password?: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reddb-io/client",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Thin remote-only RedDB driver. Downloads the `red_client` binary on install. Speaks RedWire/gRPC/HTTP. Embedded URIs (memory://, file://, red:///path) are rejected — use @reddb-io/sdk for those.",
   "type": "module",
   "main": "src/index.js",

package/src/core/url.js

@@ -20,7 +20,7 @@ import { RedDBError } from './errors.js'
 
 /**
  * @typedef {object} ParsedUri
- * @property {'embedded' | 'http' | 'https' | 'red' | 'reds' | 'redwss' | 'grpc' | 'grpcs' | 'pg'} kind
+ * @property {'embedded' | 'http' | 'https' | 'red' | 'reds' | 'redws' | 'redwss' | 'grpc' | 'grpcs' | 'pg'} kind
  * @property {string} [host]
  * @property {number} [port]
  * @property {string} [path]            // for embedded `file://`-equivalent
@@ -35,8 +35,8 @@ import { RedDBError } from './errors.js'
 
 /**
  * Parse any URI string into a normalised `ParsedUri`.
- * Accepts `red://`, `memory://`, `file://`, `grpc://` (the latter
- * three for backwards compat).
+ * Accepts `red://`, `ws(s)://`, `memory://`, `file://`, `grpc://`
+ * (the latter three for backwards compat).
  *
  * @param {string} uri
  * @returns {ParsedUri}
@@ -48,7 +48,16 @@ export function parseUri(uri) {
     )
   }
   if (uri.startsWith('red+wss://')) {
-    return parseRedWssUrl(uri)
+    return parseRedWebSocketUrl(uri, 'red+wss')
+  }
+  if (uri.startsWith('red+ws://')) {
+    return parseRedWebSocketUrl(uri, 'red+ws')
+  }
+  if (uri.startsWith('wss://')) {
+    return parseRedWebSocketUrl(uri, 'wss')
+  }
+  if (uri.startsWith('ws://')) {
+    return parseRedWebSocketUrl(uri, 'ws')
   }
   if (uri.startsWith('red://') || uri === 'red:' || uri === 'red:/') {
     return parseRedUrl(uri)
@@ -57,28 +66,35 @@ export function parseUri(uri) {
 }
 
 /**
- * Parse `red+wss://[user:pass@]host:port[?token=...]` — RedWire framing
+ * Parse `ws(s)://[user:pass@]host:port[?token=...]` — RedWire framing
  * tunneled over a binary WebSocket (the browser transport; #937, ADR
- * 0036). Resolves to a `wss://host:port/redwire` endpoint downstream.
- * Default port is 443 (the TLS edge).
+ * 0036). Resolves to a `ws(s)://host:port/redwire` endpoint downstream.
+ * TLS defaults to port 443; plaintext defaults to port 80.
  */
 export function parseRedWssUrl(uri) {
+  return parseRedWebSocketUrl(uri, 'red+wss')
+}
+
+function parseRedWebSocketUrl(uri, scheme) {
+  const tls = scheme === 'red+wss' || scheme === 'wss'
+  const prefix = `${scheme}://`
   let parsed
   try {
     // Borrow the URL parser via an `https://` authority so user / pass /
     // host / port / query all decode with the standard rules.
-    parsed = new URL('https://' + uri.slice('red+wss://'.length))
+    parsed = new URL('https://' + uri.slice(prefix.length))
   } catch (err) {
     throw new RedDBError('UNPARSEABLE_URI', `failed to parse '${uri}': ${err.message}`)
   }
   if (!parsed.hostname) {
-    throw new TypeError(`invalid red+wss:// URI: missing host in '${uri}'`)
+    throw new TypeError(`invalid ${prefix} URI: missing host in '${uri}'`)
   }
   const params = parsed.searchParams
   return {
-    kind: 'redwss',
+    kind: tls ? 'redwss' : 'redws',
     host: parsed.hostname,
-    port: parsed.port ? Number(parsed.port) : 443,
+    port: parsed.port ? Number(parsed.port) : (tls ? 443 : 80),
+    tls,
     username: parsed.username ? decodeURIComponent(parsed.username) : undefined,
     password: parsed.password ? decodeURIComponent(parsed.password) : undefined,
     token: params.get('token') ?? undefined,
@@ -239,7 +255,7 @@ export function parseLegacyUrl(uri) {
   }
   throw new RedDBError(
     'UNSUPPORTED_SCHEME',
-    `unsupported URI: '${uri}'. Use 'red://...' or one of memory://, file://, grpc://, http(s)://`,
+    `unsupported URI: '${uri}'. Use 'red://...' or one of memory://, file://, grpc://, http(s)://, ws(s)://`,
   )
 }
 
@@ -280,6 +296,10 @@ function defaultPortFor(kind) {
     case 'reds':
     case 'redwire':
       return 5050
+    case 'redws':
+      return 80
+    case 'redwss':
+      return 443
     case 'grpc':
       return 55055
     case 'grpcs':

package/src/index.browser.js

@@ -7,6 +7,7 @@
  *
  *   - 'http://host:port'   — HTTP JSON-RPC over `fetch`
  *   - 'https://host:port'  — HTTPS JSON-RPC over `fetch`
+ *   - 'ws(s)://host:port'  — RedWire over binary WebSocket
  *
  * Streaming is the Web-streams implementation (`./streaming-web.js`), so the
  * full transport-agnostic surface works client-side: query, execute, insert,
@@ -72,18 +73,18 @@ function browserTransportError(scheme) {
     `'${scheme}' connections are not available in the browser: the `
       + `browser sandbox exposes no raw TCP socket (red://, reds://, pg) or `
       + `HTTP/2 client (grpc://, grpcs://) to JavaScript. Connect to an `
-      + `HTTP(S) endpoint instead — e.g. 'http://host:port' / `
-      + `'https://host:port' — by running RedDB's HTTP JSON-RPC listener or `
-      + `an HTTP gateway in front of the server, then call `
-      + `connect('https://…').`,
+      + `HTTP(S) endpoint or RedWire WebSocket endpoint instead — e.g. `
+      + `'http://host:port' / 'https://host:port' / 'wss://host' — by running `
+      + `RedDB's HTTP JSON-RPC listener, its WebSocket edge, or an HTTP gateway `
+      + `in front of the server.`,
   )
 }
 
 /**
  * Connect to a remote RedDB instance from a browser.
  *
- * @param {string} uri Connection URI. Only `http(s)://` is reachable from a
- *   browser; other schemes raise `BROWSER_TRANSPORT_UNSUPPORTED`.
+ * @param {string} uri Connection URI. `http(s)://` and `ws(s)://` are
+ *   reachable from a browser; other schemes raise `BROWSER_TRANSPORT_UNSUPPORTED`.
  * @param {object} [options]
  * @param {object} [options.auth] Authentication credentials.
  * @param {string} [options.auth.token] Bearer / API-key token.
@@ -128,11 +129,12 @@ export async function connect(uri, options = {}) {
   // a WSS the sandbox can open. The TLS edge enforces the Origin allowlist
   // and WSS-only on its side; here we just open the socket and run the
   // standard RedWire handshake over it.
-  if (parsed.kind === 'redwss') {
+  if (parsed.kind === 'redws' || parsed.kind === 'redwss') {
     const merged = mergeAuthFromUri(parsed, options.auth)
     let token = merged.token
     if (!token && merged.username && merged.password) {
-      const loginUrl = merged.loginUrl ?? `https://${parsed.host}:${parsed.port}/auth/login`
+      const httpScheme = parsed.tls === false ? 'http' : 'https'
+      const loginUrl = merged.loginUrl ?? `${httpScheme}://${parsed.host}:${parsed.port}/auth/login`
       const session = await login(loginUrl, {
         username: merged.username,
         password: merged.password,
@@ -140,7 +142,8 @@ export async function connect(uri, options = {}) {
       token = session.token
     }
     const auth = token ? { kind: 'bearer', token } : { kind: 'anonymous' }
-    const url = `wss://${parsed.host}:${parsed.port}${REDWIRE_WS_PATH}`
+    const wsScheme = parsed.tls === false ? 'ws' : 'wss'
+    const url = `${wsScheme}://${parsed.host}:${parsed.port}${REDWIRE_WS_PATH}`
     const client = await connectRedwireWs({ url, auth })
     return new RedDB(client)
   }

package/src/redwire-ws.js

@@ -128,7 +128,7 @@ function waitOpen(ws) {
  * Open a RedWire connection over a binary WebSocket.
  *
  * @param {object} opts
- * @param {string} [opts.url] `wss://host:port/redwire` endpoint.
+ * @param {string} [opts.url] `ws(s)://host:port/redwire` endpoint.
  * @param {{ kind: 'anonymous' } | { kind: 'bearer', token: string }} [opts.auth]
  * @param {string} [opts.clientName]
  * @param {string} [opts.subprotocol] Override the advertised subprotocol.
@@ -153,10 +153,10 @@ export async function connectRedwireWs(opts = {}) {
       'no global WebSocket in this runtime; pass opts.WebSocketImpl',
     )
   }
-  if (typeof url !== 'string' || !url.startsWith('wss://')) {
+  if (typeof url !== 'string' || !(url.startsWith('wss://') || url.startsWith('ws://'))) {
     throw new RedDBError(
-      'WSS_REQUIRED',
-      `redwire websocket requires a wss:// url, got '${url}'`,
+      'WEBSOCKET_URL_REQUIRED',
+      `redwire websocket requires a ws:// or wss:// url, got '${url}'`,
     )
   }