@rip-lang/server 1.3.117 → 1.3.118

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rip-lang/server",
-  "version": "1.3.117",
+  "version": "1.3.118",
   "description": "Pure Rip web framework and application server",
   "type": "module",
   "main": "api.rip",
@@ -45,7 +45,7 @@
   "author": "Steve Shreeve <steve.shreeve@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "rip-lang": ">=3.13.122"
+    "rip-lang": ">=3.13.123"
   },
   "files": [
     "api.rip",
@@ -59,6 +59,7 @@
     "control/",
     "docs/",
     "edge/",
+    "streams/",
     "tests/",
     "README.md"
   ]

package/streams/config.rip

@@ -0,0 +1,120 @@
+# ==============================================================================
+# streams/config.rip — stream config normalization and validation
+# ==============================================================================
+
+isPlainObject = (value) ->
+  value? and typeof value is 'object' and not Array.isArray(value)
+
+pushError = (errors, code, path, message, hint = null) ->
+  errors.push({ code, path, message, hint })
+
+normalizePositiveInt = (value, fallback, path, errors, label) ->
+  return fallback unless value?
+  n = parseInt(String(value))
+  unless Number.isFinite(n) and n >= 0
+    pushError(errors, 'E_STREAM_NUMBER', path, "#{label} must be a non-negative integer", "Set #{path.split('.').slice(-1)[0]}: #{fallback} or another whole number.")
+    return fallback
+  n
+
+normalizeSniPatterns = (value, path, errors) ->
+  patterns = []
+  unless Array.isArray(value) and value.length > 0
+    pushError(errors, 'E_STREAM_SNI', path, 'sni must be a non-empty array of host patterns', "Use `sni: ['incus.example.com']`.")
+    return patterns
+  for host, idx in value
+    unless typeof host is 'string' and host.trim()
+      pushError(errors, 'E_STREAM_SNI_VALUE', "#{path}[#{idx}]", 'sni entry must be a non-empty string', "Use `'incus.example.com'` or `'*.example.com'`.")
+      continue
+    normalized = host.trim().toLowerCase()
+    if normalized.startsWith('*.')
+      base = normalized.slice(2)
+      labels = base.split('.').filter(Boolean)
+      if labels.length < 2
+        pushError(errors, 'E_STREAM_SNI_WILDCARD', "#{path}[#{idx}]", 'wildcard SNI patterns must have a base domain with at least two labels', "Use `'*.example.com'`, not `'*.com'`.")
+        continue
+    else if normalized.includes(':')
+      pushError(errors, 'E_STREAM_SNI_PORT', "#{path}[#{idx}]", 'SNI patterns must not include a port', "Use `'incus.example.com'`, not `'incus.example.com:8443'`.")
+      continue
+    patterns.push(normalized)
+  patterns
+
+export parseHostPort = (value) ->
+  return null unless typeof value is 'string'
+  idx = value.lastIndexOf(':')
+  return null unless idx > 0 and idx < value.length - 1
+  host = value.slice(0, idx)
+  port = parseInt(value.slice(idx + 1))
+  return null unless host and Number.isFinite(port) and port > 0 and port <= 65535
+  { host, port }
+
+normalizeStreamTarget = (target, idx, path, errors) ->
+  parsed = parseHostPort(target)
+  unless parsed
+    pushError(errors, 'E_STREAM_TARGET', "#{path}[#{idx}]", 'stream target must be in host:port form', "Use `'127.0.0.1:8443'`.")
+    return null
+  {
+    targetId: "#{parsed.host}:#{parsed.port}"
+    host:     parsed.host
+    port:     parsed.port
+    source:   target
+  }
+
+export normalizeStreamUpstreams = (rawUpstreams, errors, path = 'streamUpstreams') ->
+  upstreams = {}
+  return upstreams unless rawUpstreams?
+  unless isPlainObject(rawUpstreams)
+    pushError(errors, 'E_STREAM_UPSTREAMS_TYPE', path, 'streamUpstreams must be an object keyed by upstream ID', "Use `streamUpstreams: { incus: { targets: ['127.0.0.1:8443'] } }`.")
+    return upstreams
+  for upstreamId, rawConfig of rawUpstreams
+    unless isPlainObject(rawConfig)
+      pushError(errors, 'E_STREAM_UPSTREAM_TYPE', "#{path}.#{upstreamId}", 'stream upstream config must be an object', "Use #{upstreamId}: { targets: ['127.0.0.1:8443'] }.")
+      continue
+    targets = []
+    unless Array.isArray(rawConfig.targets) and rawConfig.targets.length > 0
+      pushError(errors, 'E_STREAM_UPSTREAM_TARGETS', "#{path}.#{upstreamId}.targets", 'stream upstream must define at least one target', "Use `targets: ['127.0.0.1:8443']`.")
+    else
+      for target, idx in rawConfig.targets
+        normalized = normalizeStreamTarget(target, idx, "#{path}.#{upstreamId}.targets", errors)
+        targets.push(normalized) if normalized
+    upstreams[upstreamId] =
+      id:               upstreamId
+      targets:          targets
+      connectTimeoutMs: normalizePositiveInt(rawConfig.connectTimeoutMs, 5000, "#{path}.#{upstreamId}.connectTimeoutMs", errors, 'connectTimeoutMs')
+  upstreams
+
+normalizeStreamTimeouts = (value, path, errors) ->
+  return {} unless value?
+  unless isPlainObject(value)
+    pushError(errors, 'E_STREAM_TIMEOUTS', path, 'stream timeouts must be an object', "Use `timeouts: { handshakeMs: 5000, idleMs: 300000, connectMs: 5000 }`.")
+    return {}
+  {
+    handshakeMs: normalizePositiveInt(value.handshakeMs, 5000, "#{path}.handshakeMs", errors, 'handshakeMs')
+    idleMs: normalizePositiveInt(value.idleMs, 300000, "#{path}.idleMs", errors, 'idleMs')
+    connectMs: normalizePositiveInt(value.connectMs, 5000, "#{path}.connectMs", errors, 'connectMs')
+  }
+
+export normalizeStreams = (rawStreams, knownUpstreams, errors, path = 'streams') ->
+  streams = []
+  return streams unless rawStreams?
+  unless Array.isArray(rawStreams)
+    pushError(errors, 'E_STREAMS_TYPE', path, 'streams must be an array', "Use `streams: [{ listen: 8443, sni: ['incus.example.com'], upstream: 'incus' }]`.")
+    return streams
+  for route, idx in rawStreams
+    itemPath = "#{path}[#{idx}]"
+    unless isPlainObject(route)
+      pushError(errors, 'E_STREAM_ROUTE_TYPE', itemPath, 'stream route must be an object', "Use `{ listen: 8443, sni: ['incus.example.com'], upstream: 'incus' }`.")
+      continue
+    listen = normalizePositiveInt(route.listen, 0, "#{itemPath}.listen", errors, 'listen')
+    pushError(errors, 'E_STREAM_LISTEN_RANGE', "#{itemPath}.listen", 'listen port must be between 1 and 65535', 'Choose a valid TCP port.') unless listen > 0 and listen <= 65535
+    unless typeof route.upstream is 'string' and route.upstream
+      pushError(errors, 'E_STREAM_UPSTREAM_REF', "#{itemPath}.upstream", 'stream route must reference an upstream', "Use `upstream: 'incus'`.")
+    else unless knownUpstreams.has(route.upstream)
+      pushError(errors, 'E_STREAM_UPSTREAM_REF', "#{itemPath}.upstream", "unknown stream upstream #{route.upstream}", 'Define the upstream under `streamUpstreams` first.')
+    streams.push
+      id:       route.id or "stream-#{idx + 1}"
+      order:    idx
+      listen:   listen
+      sni:      normalizeSniPatterns(route.sni, "#{itemPath}.sni", errors)
+      upstream: route.upstream or null
+      timeouts: normalizeStreamTimeouts(route.timeouts, "#{itemPath}.timeouts", errors)
+  streams

package/streams/index.rip

@@ -0,0 +1,288 @@
+# ==============================================================================
+# streams/index.rip — stream runtime facade and listener orchestration
+# ==============================================================================
+
+import { parseSNI } from './tls_clienthello.rip'
+import { compileStreamTable, matchStreamRoute, describeStreamRoute } from './router.rip'
+import { createStreamRuntime, buildStreamConfigInfo, describeStreamRuntime } from './runtime.rip'
+import { createStreamUpstreamPool, addStreamUpstream, getStreamUpstream, selectStreamTarget, openStreamConnection, releaseStreamConnection } from './upstream.rip'
+import { createPipeState, writeChunk, flushPending, markPaused, markResumed } from './pipe.rip'
+
+MAX_CLIENT_HELLO_BYTES = 16384
+MAX_CONNECT_BUFFER_BYTES = 262144
+
+concatBytes = (a, b) ->
+  out = new Uint8Array(a.byteLength + b.byteLength)
+  out.set(a, 0)
+  out.set(b, a.byteLength)
+  out
+
+export resolveHandshakeTarget = (runtime, listenPort, sni, httpFallback = {}) ->
+  route = matchStreamRoute(runtime.routeTable, listenPort, sni)
+  if route
+    upstream = getStreamUpstream(runtime.upstreamPool, route.upstream)
+    unless upstream
+      return {
+        kind: 'reject'
+        code: 'unknown_upstream'
+      }
+    target = selectStreamTarget(upstream)
+    unless target
+      return {
+        kind: 'reject'
+        code: 'no_available_target'
+      }
+    return {
+      kind: 'stream'
+      route: route
+      upstream: upstream
+      target: target
+    }
+
+  fallback = httpFallback?[listenPort] or null
+  return {
+    kind: 'fallback'
+    target: fallback
+  } if fallback
+  {
+    kind: 'reject'
+    code: 'no_matching_route'
+  }
+
+export buildStreamRuntime = (normalized) ->
+  routeTable = compileStreamTable(normalized.streams or [])
+  upstreamPool = createStreamUpstreamPool()
+  for upstreamId, upstreamConfig of (normalized.streamUpstreams or {})
+    addStreamUpstream(upstreamPool, upstreamId, upstreamConfig)
+  configInfo = buildStreamConfigInfo(normalized)
+  createStreamRuntime(configInfo, upstreamPool, routeTable)
+
+export streamDiagnostics = (runtime) ->
+  return null unless runtime
+  summary = describeStreamRuntime(runtime)
+  summary.upstreams = Array.from(runtime.upstreamPool.upstreams.values()).map (upstream) ->
+    id: upstream.id
+    activeConnections: upstream.targets.reduce(((sum, t) -> sum + t.activeConnections), 0)
+    totalConnections: upstream.targets.reduce(((sum, t) -> sum + t.totalConnections), 0)
+    targets: upstream.targets.map (t) ->
+      id: t.targetId
+      activeConnections: t.activeConnections
+      totalConnections: t.totalConnections
+  summary.routes = runtime.configInfo.activeStreamRouteDescriptions or []
+  summary
+
+cleanupState = (state, options = {}) ->
+  return if state.cleanedUp
+  state.cleanedUp = true
+  clearTimeout(state.handshakeTimer) if state.handshakeTimer
+  clearTimeout(state.connectTimer) if state.connectTimer
+  clearTimeout(state.idleTimer) if state.idleTimer
+  try state.client.close() if state.client?.readyState > 0
+  try state.upstream.close() if state.upstream?.readyState > 0
+  releaseStreamConnection(state.target) if state.target and state.connectionOpened
+  options.onConnectionClose?(state.runtime)
+
+finishHalfClose = (state) ->
+  if state.clientEnded and not state.upstreamFinSent and state.toUpstream.pending.byteLength is 0
+    state.upstreamFinSent = true
+    try state.upstream?.end()
+  if state.upstreamEnded and not state.clientFinSent and state.toClient.pending.byteLength is 0
+    state.clientFinSent = true
+    try state.client?.end()
+
+resetIdleTimer = (state, options) ->
+  clearTimeout(state.idleTimer) if state.idleTimer
+  idleMs = state.timeouts.idleMs or 300000
+  state.idleTimer = setTimeout((-> cleanupState(state, options)), idleMs)
+
+createUpstreamHandlers = (state, options) ->
+  open: (upstream) ->
+    if state.cleanedUp
+      try upstream.close()
+      return
+    try
+      state.upstream = upstream
+      clearTimeout(state.connectTimer) if state.connectTimer
+      state.phase = 'streaming'
+      res = writeChunk(upstream, state.toUpstream, state.buffer)
+      return cleanupState(state, options) if res.closed
+      state.buffer = new Uint8Array(0)
+      if res.needDrain
+        state.clientPaused = true
+        markPaused(state.client)
+      resetIdleTimer(state, options)
+      finishHalfClose(state) unless res.needDrain
+    catch
+      cleanupState(state, options)
+
+  data: (upstream, data) ->
+    return if state.cleanedUp
+    resetIdleTimer(state, options)
+    res = writeChunk(state.client, state.toClient, new Uint8Array(data))
+    return cleanupState(state, options) if res.closed
+    if res.needDrain
+      state.upstreamPaused = true
+      markPaused(upstream)
+
+  drain: (upstream) ->
+    return if state.cleanedUp
+    res = flushPending(upstream, state.toUpstream)
+    return cleanupState(state, options) if res.closed
+    unless res.needDrain
+      if state.clientPaused
+        state.clientPaused = false
+        markResumed(state.client)
+      finishHalfClose(state)
+
+  end: (upstream) ->
+    return if state.cleanedUp
+    state.upstreamEnded = true
+    finishHalfClose(state)
+
+  close: (upstream, err) ->
+    cleanupState(state, options)
+
+  error: (upstream, err) ->
+    cleanupState(state, options)
+
+  timeout: (upstream) ->
+    cleanupState(state, options)
+
+  connectError: (upstream, err) ->
+    cleanupState(state, options)
+
+createClientHandlers = (runtime, listenPort, listenerTimeouts, options) ->
+  listenerOptions = Object.assign({}, options)
+  socket:
+    open: (client) ->
+      timeouts = Object.assign({ handshakeMs: 5000, idleMs: 300000, connectMs: 5000 }, listenerTimeouts or {}, options.timeouts or {})
+      state =
+        runtime: runtime
+        client: client
+        upstream: null
+        listenPort: listenPort
+        phase: 'handshake'
+        buffer: new Uint8Array(0)
+        route: null
+        target: null
+        cleanedUp: false
+        clientPaused: false
+        upstreamPaused: false
+        toUpstream: createPipeState()
+        toClient: createPipeState()
+        clientEnded: false
+        upstreamEnded: false
+        clientFinSent: false
+        upstreamFinSent: false
+        connectionOpened: false
+        handshakeTimer: null
+        connectTimer: null
+        idleTimer: null
+        timeouts: timeouts
+      client.data = state
+      state.handshakeTimer = setTimeout((-> cleanupState(state, listenerOptions)), timeouts.handshakeMs)
+      options.onConnectionOpen?(runtime)
+
+    data: (client, data) ->
+      state = client.data
+      return if state.cleanedUp
+      resetIdleTimer(state, listenerOptions) if state.phase is 'streaming'
+
+      if state.phase is 'handshake'
+        next = new Uint8Array(data)
+        state.buffer = if state.buffer.byteLength > 0 then concatBytes(state.buffer, next) else next
+        return cleanupState(state, listenerOptions) if state.buffer.byteLength > MAX_CLIENT_HELLO_BYTES
+
+        parsed = parseSNI(state.buffer)
+        return if parsed.code is 'need_more_bytes'
+        hasFallback = Boolean(options.httpFallback?[state.listenPort])
+        return cleanupState(state, listenerOptions) unless parsed.ok or (parsed.code is 'no_sni' and hasFallback)
+
+        requestedSni = if parsed.ok then parsed.sni else null
+        result = resolveHandshakeTarget(runtime, state.listenPort, requestedSni, options.httpFallback or {})
+        return cleanupState(state, listenerOptions) if result.kind is 'reject'
+
+        state.route = result.route or null
+        state.target = if result.kind is 'stream' then result.target else null
+        state.timeouts = if result.kind is 'stream'
+          Object.assign({}, state.timeouts, result.route.timeouts or {}, connectMs: result.route.timeouts?.connectMs or result.upstream.connectTimeoutMs or state.timeouts.connectMs)
+        else
+          Object.assign({}, state.timeouts)
+
+        connectHost = if result.kind is 'stream' then result.target.host else result.target.hostname
+        connectPort = result.target.port
+        openStreamConnection(result.target) if result.kind is 'stream'
+        state.connectionOpened = result.kind is 'stream'
+        state.phase = 'connecting'
+        clearTimeout(state.handshakeTimer) if state.handshakeTimer
+        state.connectTimer = setTimeout((-> cleanupState(state, listenerOptions)), state.timeouts.connectMs or 5000)
+        Bun.connect(
+          hostname: connectHost
+          port: connectPort
+          allowHalfOpen: true
+          socket: createUpstreamHandlers(state, listenerOptions)
+        ).catch(-> cleanupState(state, listenerOptions))
+        return
+
+      if state.phase is 'connecting'
+        next = new Uint8Array(data)
+        state.buffer = if state.buffer.byteLength > 0 then concatBytes(state.buffer, next) else next
+        return cleanupState(state, listenerOptions) if state.buffer.byteLength > MAX_CONNECT_BUFFER_BYTES
+        return
+
+      if state.phase is 'streaming'
+        res = writeChunk(state.upstream, state.toUpstream, new Uint8Array(data))
+        return cleanupState(state, listenerOptions) if res.closed
+        if res.needDrain
+          state.clientPaused = true
+          markPaused(client)
+
+    drain: (client) ->
+      state = client.data
+      return if state.cleanedUp
+      res = flushPending(client, state.toClient)
+      return cleanupState(state, listenerOptions) if res.closed
+      unless res.needDrain
+        if state.upstreamPaused
+          state.upstreamPaused = false
+          markResumed(state.upstream)
+        finishHalfClose(state)
+
+    end: (client) ->
+      state = client.data
+      return if state.cleanedUp
+      state.clientEnded = true
+      finishHalfClose(state)
+
+    close: (client, err) ->
+      cleanupState(client.data, listenerOptions)
+
+    error: (client, err) ->
+      cleanupState(client.data, listenerOptions)
+
+export startStreamListeners = (runtime, options = {}) ->
+  routesByPort = new Map()
+  for route in (runtime.routeTable.routes or [])
+    list = routesByPort.get(route.listen) or []
+    list.push(route)
+    routesByPort.set(route.listen, list)
+  ports = Array.from(routesByPort.keys())
+  for port in ports
+    portRoutes = routesByPort.get(port) or []
+    listenerTimeouts =
+      handshakeMs: Math.max(...portRoutes.map((route) -> route.timeouts?.handshakeMs or 5000), 5000)
+      idleMs: Math.max(...portRoutes.map((route) -> route.timeouts?.idleMs or 300000), 300000)
+      connectMs: Math.max(...portRoutes.map((route) -> route.timeouts?.connectMs or 5000), 5000)
+    listener = Bun.listen
+      hostname: options.hostname or '0.0.0.0'
+      port: port
+      allowHalfOpen: true
+      socket: createClientHandlers(runtime, port, listenerTimeouts, options).socket
+    runtime.listeners.set(port, listener)
+  runtime
+
+export stopStreamListeners = (runtime, closeActiveConnections = false) ->
+  for [port, listener] as runtime.listeners
+    try listener.stop(closeActiveConnections)
+  runtime.listeners.clear()
+  runtime

package/streams/pipe.rip

@@ -0,0 +1,56 @@
+# ==============================================================================
+# streams/pipe.rip — backpressure-safe socket write helpers
+# ==============================================================================
+
+toBytes = (data) ->
+  if data instanceof Uint8Array then data else new Uint8Array(data)
+
+concatBytes = (a, b) ->
+  a = toBytes(a)
+  b = toBytes(b)
+  out = new Uint8Array(a.byteLength + b.byteLength)
+  out.set(a, 0)
+  out.set(b, a.byteLength)
+  out
+
+export createPipeState = ->
+  pending: new Uint8Array(0)
+  waitingForDrain: false
+
+queuePending = (state, data, wrote) ->
+  bytes = toBytes(data)
+  remainder = bytes.subarray(Math.max(0, wrote))
+  state.pending = if state.pending.byteLength > 0 then concatBytes(state.pending, remainder) else new Uint8Array(remainder)
+  state.waitingForDrain = state.pending.byteLength > 0
+  state
+
+export writeChunk = (socket, state, data) ->
+  bytes = toBytes(data)
+  if state.pending.byteLength > 0
+    state.pending = concatBytes(state.pending, bytes)
+    state.waitingForDrain = true
+    return { ok: true, closed: false, wrote: 0, buffered: state.pending.byteLength, needDrain: true }
+  wrote = socket.write(bytes)
+  return { ok: false, closed: true, wrote: -1, buffered: state.pending.byteLength } if wrote < 0
+  if wrote < bytes.byteLength
+    queuePending(state, bytes, wrote)
+    return { ok: true, closed: false, wrote: wrote, buffered: state.pending.byteLength, needDrain: true }
+  { ok: true, closed: false, wrote: wrote, buffered: state.pending.byteLength, needDrain: false }
+
+export flushPending = (socket, state) ->
+  return { ok: true, closed: false, wrote: 0, buffered: 0, needDrain: false } unless state.pending.byteLength > 0
+  wrote = socket.write(state.pending)
+  return { ok: false, closed: true, wrote: -1, buffered: state.pending.byteLength } if wrote < 0
+  if wrote < state.pending.byteLength
+    state.pending = new Uint8Array(state.pending.subarray(wrote))
+    state.waitingForDrain = true
+    return { ok: true, closed: false, wrote: wrote, buffered: state.pending.byteLength, needDrain: true }
+  state.pending = new Uint8Array(0)
+  state.waitingForDrain = false
+  { ok: true, closed: false, wrote: wrote, buffered: 0, needDrain: false }
+
+export markPaused = (socket) ->
+  socket.pause?()
+
+export markResumed = (socket) ->
+  socket.resume?()

package/streams/router.rip

@@ -0,0 +1,57 @@
+# ==============================================================================
+# streams/router.rip — stream route compilation and matching
+# ==============================================================================
+
+sniKind = (pattern) ->
+  return 'wildcard' if typeof pattern is 'string' and pattern.startsWith('*.')
+  'exact'
+
+wildcardMatch = (pattern, hostname) ->
+  return false unless typeof pattern is 'string' and pattern.startsWith('*.')
+  suffix = pattern.slice(1)
+  return false unless hostname.endsWith(suffix)
+  prefix = hostname.slice(0, hostname.length - suffix.length)
+  prefix.length > 0 and not prefix.includes('.')
+
+sniMatches = (pattern, hostname) ->
+  if sniKind(pattern) is 'exact'
+    hostname is pattern
+  else
+    wildcardMatch(pattern, hostname)
+
+sniScore = (pattern) ->
+  if sniKind(pattern) is 'exact' then 20 else 10
+
+export compileStreamTable = (routes = []) ->
+  compiled = []
+  for route in routes
+    for pattern in (route.sni or [])
+      compiled.push
+        id: route.id
+        order: route.order or 0
+        listen: route.listen
+        upstream: route.upstream
+        sni: pattern
+        sniKind: sniKind(pattern)
+        timeouts: route.timeouts or {}
+  { routes: compiled }
+
+export matchStreamRoute = (table, listenPort, sni) ->
+  host = String(sni or '').toLowerCase()
+  best = null
+  for route in (table?.routes or [])
+    continue unless route.listen is listenPort
+    continue unless sniMatches(route.sni, host)
+    better = false
+    if not best
+      better = true
+    else if sniScore(route.sni) > sniScore(best.sni)
+      better = true
+    else if sniScore(route.sni) is sniScore(best.sni) and route.order < best.order
+      better = true
+    best = route if better
+  best
+
+export describeStreamRoute = (route) ->
+  return null unless route
+  "#{route.listen} #{route.sni} -> #{route.upstream}"

package/streams/runtime.rip

@@ -0,0 +1,51 @@
+# ==============================================================================
+# streams/runtime.rip — stream runtime lifecycle helpers
+# ==============================================================================
+
+import { createStreamUpstreamPool } from './upstream.rip'
+import { compileStreamTable, describeStreamRoute } from './router.rip'
+
+export createStreamRuntime = (configInfo = null, upstreamPool = null, routeTable = null) ->
+  upstreamPool = upstreamPool or createStreamUpstreamPool()
+  routeTable = routeTable or compileStreamTable()
+  configInfo = configInfo or {
+    streamCounts:
+      streamUpstreams: 0
+      streams: 0
+    activeStreamRouteDescriptions: []
+  }
+  {
+    id: "stream-#{Date.now()}-#{Math.random().toString(16).slice(2, 8)}"
+    upstreamPool: upstreamPool
+    routeTable: routeTable
+    listeners: new Map()
+    inflight: 0
+    retiredAt: null
+    configInfo: configInfo
+  }
+
+export describeStreamRuntime = (runtime) ->
+  return null unless runtime
+  {
+    id: runtime.id
+    inflight: runtime.inflight
+    retiredAt: runtime.retiredAt
+    listeners: Array.from(runtime.listeners.keys())
+  }
+
+export streamUsesListenPort = (runtimeOrRoutes, listenPort) ->
+  return false unless typeof listenPort is 'number'
+  routes = if runtimeOrRoutes?.routeTable?.routes
+    runtimeOrRoutes.routeTable.routes
+  else
+    runtimeOrRoutes or []
+  (routes or []).some((route) -> route?.listen is listenPort)
+
+export buildStreamConfigInfo = (normalized) ->
+  routeTable = compileStreamTable(normalized.streams or [])
+  {
+    streamCounts:
+      streamUpstreams: Object.keys(normalized.streamUpstreams or {}).length
+      streams: (normalized.streams or []).length
+    activeStreamRouteDescriptions: (routeTable.routes or []).map(describeStreamRoute).filter(Boolean)
+  }

package/streams/tls_clienthello.rip

@@ -0,0 +1,89 @@
+# ==============================================================================
+# streams/tls_clienthello.rip — minimal ClientHello SNI extractor
+# ==============================================================================
+
+MAX_CLIENT_HELLO_BYTES = 16384
+
+u16 = (buf, idx) -> (buf[idx] << 8) | buf[idx + 1]
+u24 = (buf, idx) -> (buf[idx] << 16) | (buf[idx + 1] << 8) | buf[idx + 2]
+
+fail = (code, message, needMoreBytes = false) ->
+  { ok: false, code, message, needMoreBytes }
+
+export parseSNI = (input) ->
+  buf = if input instanceof Uint8Array then input else new Uint8Array(input or [])
+  len = buf.length
+
+  return fail('need_more_bytes', 'need at least 5 bytes for TLS record header', true) if len < 5
+  return fail('bad_record_type', 'expected TLS handshake record') unless buf[0] is 0x16
+
+  recordLen = u16(buf, 3)
+  totalLen = 5 + recordLen
+  return fail('client_hello_too_large', "ClientHello exceeds #{MAX_CLIENT_HELLO_BYTES} byte cap") if totalLen > MAX_CLIENT_HELLO_BYTES
+  return fail('need_more_bytes', 'partial TLS record', true) if len < totalLen
+
+  return fail('need_more_bytes', 'need handshake header', true) if totalLen < 9
+  return fail('bad_handshake_type', 'expected TLS ClientHello handshake') unless buf[5] is 0x01
+
+  helloLen = u24(buf, 6)
+  helloEnd = 9 + helloLen
+  return fail('need_more_bytes', 'partial ClientHello', true) if len < helloEnd
+
+  cursor = 9
+  return fail('need_more_bytes', 'need client version and random', true) if cursor + 34 > helloEnd
+  cursor += 34
+
+  return fail('need_more_bytes', 'need session ID length', true) if cursor + 1 > helloEnd
+  sessionLen = buf[cursor]
+  cursor++
+  return fail('bad_session_id_length', 'session ID exceeds ClientHello bounds') if cursor + sessionLen > helloEnd
+  cursor += sessionLen
+
+  return fail('need_more_bytes', 'need cipher suites length', true) if cursor + 2 > helloEnd
+  cipherLen = u16(buf, cursor)
+  cursor += 2
+  return fail('bad_cipher_length', 'cipher suite list exceeds ClientHello bounds') if cursor + cipherLen > helloEnd
+  cursor += cipherLen
+
+  return fail('need_more_bytes', 'need compression methods length', true) if cursor + 1 > helloEnd
+  compressionLen = buf[cursor]
+  cursor++
+  return fail('bad_compression_length', 'compression methods exceed ClientHello bounds') if cursor + compressionLen > helloEnd
+  cursor += compressionLen
+
+  return fail('no_sni', 'ClientHello has no extensions') if cursor is helloEnd
+  return fail('need_more_bytes', 'need extensions length', true) if cursor + 2 > helloEnd
+  extensionsLen = u16(buf, cursor)
+  cursor += 2
+  extensionsEnd = cursor + extensionsLen
+  return fail('bad_extensions_length', 'extensions exceed ClientHello bounds') if extensionsEnd > helloEnd
+
+  decoder = new TextDecoder()
+
+  while cursor < extensionsEnd
+    return fail('bad_extension_header', 'incomplete extension header') if cursor + 4 > extensionsEnd
+    extType = u16(buf, cursor)
+    extLen = u16(buf, cursor + 2)
+    cursor += 4
+    return fail('bad_extension_length', 'extension data exceeds extensions bounds') if cursor + extLen > extensionsEnd
+
+    if extType is 0x0000
+      extEnd = cursor + extLen
+      return fail('bad_sni_length', 'SNI extension too short') if cursor + 2 > extEnd
+      listLen = u16(buf, cursor)
+      cursor += 2
+      return fail('bad_sni_list_length', 'SNI list exceeds extension bounds') if cursor + listLen > extEnd
+      return fail('bad_sni_entry', 'SNI entry is incomplete') if cursor + 3 > extEnd
+      nameType = buf[cursor]
+      cursor++
+      return fail('bad_sni_type', 'only host_name SNI entries are supported') unless nameType is 0x00
+      nameLen = u16(buf, cursor)
+      cursor += 2
+      return fail('bad_sni_name_length', 'SNI hostname exceeds extension bounds') if cursor + nameLen > extEnd
+      sni = decoder.decode(buf.subarray(cursor, cursor + nameLen)).toLowerCase()
+      return fail('no_sni', 'SNI hostname is empty') unless sni
+      return { ok: true, sni, bytesConsumed: totalLen }
+
+    cursor += extLen
+
+  fail('no_sni', 'ClientHello does not include SNI')

package/streams/upstream.rip

@@ -0,0 +1,48 @@
+# ==============================================================================
+# streams/upstream.rip — stream upstream selection and accounting
+# ==============================================================================
+
+export createStreamUpstreamPool = ->
+  upstreams: new Map()
+
+export addStreamUpstream = (pool, id, config) ->
+  targets = (config.targets or []).map (target, idx) ->
+    targetId:          target.targetId or "#{target.host}:#{target.port}"
+    host:              target.host
+    port:              target.port
+    source:            target.source or "#{target.host}:#{target.port}"
+    activeConnections: 0
+    totalConnections:  0
+  upstream =
+    id:               id
+    connectTimeoutMs: config.connectTimeoutMs or 5000
+    targets:          targets
+  pool.upstreams.set(id, upstream)
+  upstream
+
+export getStreamUpstream = (pool, id) ->
+  pool.upstreams.get(id) ?? null
+
+export listStreamUpstreams = (pool) ->
+  Array.from(pool.upstreams.values())
+
+export selectStreamTarget = (upstream) ->
+  return null unless upstream?.targets?.length
+  best = upstream.targets[0]
+  for target in upstream.targets[1..]
+    better = false
+    if target.activeConnections < best.activeConnections
+      better = true
+    else if target.activeConnections is best.activeConnections and target.targetId < best.targetId
+      better = true
+    best = target if better
+  best
+
+export openStreamConnection = (target) ->
+  target.activeConnections++
+  target.totalConnections++
+  target
+
+export releaseStreamConnection = (target) ->
+  target.activeConnections = Math.max(0, target.activeConnections - 1)
+  target