@absolutejs/router 0.0.1

package/LICENSE

@@ -0,0 +1,94 @@
+# Business Source License 1.1
+
+**Licensor:** Alex Kahn
+
+**Licensed Work:** @absolutejs/router (https://github.com/absolutejs/router)
+
+**Change Date:** May 29, 2030
+
+**Change License:** Apache License, Version 2.0
+
+---
+
+## Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, permitting limited production use.
+
+### Additional Use Grant
+
+You may use the Licensed Work in production, provided your use does not include
+any of the following:
+
+1. **Offering a Competing Service.** You may not offer the Licensed Work, or
+   any derivative or substantial portion of it, to third parties as a hosted or
+   managed service that competes with a hosted multi-tenant connection router
+   or WebSocket edge gateway for application runtimes (including, but not
+   limited to, services like Cloudflare Workers WebSockets / Smart Placement,
+   Vercel's edge router, Liveblocks' WebSocket fan-out, PartyKit, Ably,
+   Pusher, Soketi, or any similar hosted offering whose primary value to its
+   users is multi-tenant connection routing, tenant-to-shard stickiness,
+   per-tenant connection capping, or per-tenant rate limiting at the network
+   edge). This includes any product whose primary value to its users is the
+   functionality the Licensed Work provides.
+
+2. **Resale or Redistribution as a Standalone Product.** You may not sell,
+   license, or distribute the Licensed Work, or any derivative or fork of it,
+   as a standalone commercial product.
+
+3. **Removal of Attribution.** Any derivative work, fork, or redistribution of
+   the Licensed Work must prominently credit AbsoluteJS and include a link to
+   the original project repository (https://github.com/absolutejs/router).
+
+For clarity, the following uses are expressly permitted:
+
+- Using the Licensed Work to build and operate your own applications, websites,
+  internal tools, or SaaS products (whether commercial or non-commercial), so
+  long as the Licensed Work itself is not the primary product you are selling.
+- Using the Licensed Work as a dependency in commercial software you build and
+  sell, as long as the software is not itself a competing managed service of
+  the kind described in clause 1.
+- Providing consulting, development, or professional services to clients using
+  the Licensed Work.
+- Forking and modifying the Licensed Work for your own internal use, provided
+  attribution is maintained.
+
+### Change Date and Change License
+
+On the Change Date specified above, or on such other date as the Licensor may
+specify by written notice, the Licensed Work will be made available under the
+Change License (Apache License, Version 2.0). Until the Change Date, the terms
+of this Business Source License 1.1 apply.
+
+### Trademark
+
+This license does not grant you any rights to use the "AbsoluteJS" or
+"@absolutejs" name, logo, or any related trademarks. Forks and derivative works
+must not be named or branded in a manner that suggests endorsement by or
+affiliation with AbsoluteJS or the Licensor.
+
+### Notices
+
+You must not remove or obscure any licensing, copyright, or other notices
+included in the Licensed Work.
+
+### No Warranty
+
+THE LICENSED WORK IS PROVIDED "AS IS". THE LICENSOR HEREBY DISCLAIMS ALL
+WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE LICENSOR 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 LICENSED WORK OR THE USE OR OTHER DEALINGS IN THE
+LICENSED WORK.
+
+---
+
+## Contact
+
+For commercial licensing inquiries or additional permissions, contact:
+
+- **Alex Kahn**
+- alexkahndev@gmail.com
+- alexkahndev.github.io

package/README.md

@@ -0,0 +1,98 @@
+# @absolutejs/router
+
+Multi-tenant connection routing primitive for Bun PaaS gateways. Sits in front
+of N backend processes (each a [`@absolutejs/runtime`](https://github.com/absolutejs/runtime)
+instance hosting a [`@absolutejs/sync`](https://github.com/absolutejs/sync) engine
+for a subset of tenants) and decides — per request:
+
+1. Which shard owns this tenant (consistent hash, sticky)
+2. Is the tenant over its connection cap?
+3. Is the tenant over its rate limit?
+4. Is the chosen shard healthy?
+
+Pure logic, zero Bun / Elysia surface. Wire `router.route(...)` into whichever
+HTTP/WS layer you have (Bun.serve, Elysia, native node:http, anything that can
+return a 503). An Elysia adapter ships in a later 0.0.x as a subpath.
+
+```ts
+import { createRouter } from '@absolutejs/router';
+
+const router = createRouter({
+  shards: [
+    { id: 'engine-1', url: 'ws://10.0.0.11:3000' },
+    { id: 'engine-2', url: 'ws://10.0.0.12:3000' },
+  ],
+  hashStrategy: 'jump',
+  perTenantConnectionCap: 100,
+  perTenantRateLimit: { tokens: 100, refillPerSecond: 10 },
+});
+
+// In your WS upgrade handler:
+const decision = router.route({ tenantId, channelId });
+if (decision.decision !== 'allow') {
+  return new Response(decision.decision, { status: 429 });
+}
+const handle = router.acquire(tenantId);
+ws.data = { ...ws.data, release: handle.release, upstream: decision.shard!.url };
+// ...proxy WS frames to decision.shard.url; call handle.release() on close.
+```
+
+## v0.0.1 surface
+
+| API | Purpose |
+|---|---|
+| `createRouter(options)` | Factory. Returns a `Router`. |
+| `router.route({ tenantId, channelId? })` | Returns `{ shard, decision }`. Decision is `allow` / `rate-limited` / `capped` / `no-shards`. |
+| `router.acquire(tenantId)` | Increment a tenant's active-connection counter; returns `{ active, release }`. `release` is idempotent. |
+| `router.markHealthy(id)` / `router.markUnhealthy(id)` | Caller-driven health state. Unhealthy shards are skipped; tenants on them rehash to healthy ones. |
+| `router.addShard(shard)` / `router.removeShard(id)` | Runtime shard membership changes. |
+| `router.shards()` / `router.snapshot()` | Inspection. |
+| `router.dispose()` | Stop accepting routes; all subsequent `route()` returns `no-shards`. |
+
+### Hash strategies
+
+- **`jump`** (default) — Lamping & Veach 2014. O(log n) with no memory, exactly
+  1/N keys move when shards are added at the tail. Ignores `weight`.
+- **`rendezvous`** — HRW hash. Supports per-shard `weight` for heterogeneous
+  engine sizes. O(N) per lookup.
+- **Custom**: pass `(key, shards) => index`.
+
+### Connection cap
+
+`perTenantConnectionCap` is the max concurrent connections one tenant can hold,
+counted via `acquire()` / the returned `release()`. When reached, `route()`
+returns `capped` — your gateway should refuse the upgrade with `429` /
+`503`. Default `Infinity` (no cap).
+
+### Rate limit
+
+`perTenantRateLimit` is a token bucket per tenant: `tokens` is bucket capacity
+AND starting balance; `refillPerSecond` continuously refills up to capacity.
+Each successful `route()` costs one token. Bucket is computed lazily at lookup
+time — no timer churn for idle tenants. Default `{ tokens: Infinity,
+refillPerSecond: 0 }` (no limit).
+
+### Health
+
+The router does not probe backends itself — keeping it bun/elysia-free means
+no I/O. Wire your own health-check loop and call `markHealthy` / `markUnhealthy`.
+A live health-checking adapter is a candidate for a later 0.0.x subpath.
+
+## Architectural role
+
+- **`@absolutejs/sync`** — the engine each backend shard runs.
+- **`@absolutejs/runtime`** — the process pool each backend shard spawns from.
+- **`@absolutejs/metering`** — counts the bill; `meter.allow(tenant)` reads.
+- **`@absolutejs/router`** — *this library*. The edge decision before traffic reaches a shard. `meter.allow()` can be wired into the gateway alongside `router.route()` to refuse over-quota tenants without paying for the upstream hop.
+
+## What v0.0.1 does NOT include
+
+- The actual WS proxy implementation. Caller wires `Bun.serve` (or any HTTP/WS layer) to `router.route()` and forwards bytes themselves.
+- The Elysia adapter (subpath in a later 0.0.x).
+- Distributed router state across multiple edge replicas (v0.2+).
+- Backend health-checking probe loop.
+- TLS / HTTP3 termination.
+
+## License
+
+BSL 1.1 with a named carveout for the hosted multi-tenant connection routing / WebSocket edge gateway category (Cloudflare Workers WebSockets, Cloudflare Smart Placement, Vercel edge router, Liveblocks' WebSocket fan-out, PartyKit, Ably, Pusher, Soketi). See [LICENSE](./LICENSE). Change Date: 4 years from first release; Change License: Apache 2.0.

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @absolutejs/router — multi-tenant connection routing primitive for Bun PaaS
+ * gateways.
+ *
+ * Sits between an incoming request / WS upgrade and N backend processes (each
+ * one a `@absolutejs/runtime` instance hosting a `@absolutejs/sync` engine
+ * for a subset of tenants). Decides which shard owns the tenant, whether the
+ * tenant is over its rate limit, whether the tenant is over its connection
+ * cap, and whether the chosen shard is healthy.
+ *
+ * v0.0.1 is intentionally bun/elysia-agnostic — pure logic, no `Bun.serve`
+ * or proxy code. The caller wires the routing decision into whichever HTTP/WS
+ * layer they have. An Elysia adapter ships in a later 0.0.x as a subpath.
+ */
+export type Shard = {
+    id: string;
+    /**
+     * Connection target for the chosen backend. Format is opaque to the router
+     * — `ws://host:port`, `https://host`, a unix socket path, whatever the
+     * caller's proxy layer understands.
+     */
+    url: string;
+    /**
+     * Relative weight for hash strategies that support it (rendezvous). Jump
+     * hash ignores weights — every shard is treated as weight 1. Default 1.
+     */
+    weight?: number;
+};
+/**
+ * Pure hash-strategy function. Given the routing key + the list of currently
+ * healthy shards (with their weights), return the index in `shards` of the
+ * chosen shard. The router never calls a strategy with an empty `shards`
+ * array — that case is handled upstream as `no-shards`.
+ */
+export type HashStrategyFn = (key: string, shards: ReadonlyArray<Shard>) => number;
+export type HashStrategy = 'jump' | 'rendezvous' | HashStrategyFn;
+/**
+ * Per-tenant token-bucket rate limit. `tokens` is the bucket capacity AND the
+ * starting balance; `refillPerSecond` is added continuously up to capacity.
+ * Defaults: `Infinity` tokens / `0` refill = no limit.
+ */
+export type RateLimit = {
+    tokens: number;
+    refillPerSecond: number;
+};
+export type RouterOptions = {
+    /** Initial shard set. Can be empty (every `route()` returns `no-shards`). */
+    shards: Shard[];
+    /** Hash strategy. Default `'jump'`. */
+    hashStrategy?: HashStrategy;
+    /**
+     * Max concurrent connections per tenant (counted via `acquire()` /
+     * `release()`). Default `Infinity` (no cap). When reached, `route()`
+     * returns `'capped'`.
+     */
+    perTenantConnectionCap?: number;
+    /**
+     * Per-tenant token bucket. Default `{ tokens: Infinity, refillPerSecond: 0 }`
+     * (no limit). When the tenant's bucket is empty, `route()` returns
+     * `'rate-limited'`. One `route()` call costs one token.
+     */
+    perTenantRateLimit?: RateLimit;
+    /** Override `Date.now` for tests. */
+    clock?: () => number;
+};
+export type RouteDecision = 'allow' | 'rate-limited' | 'capped' | 'no-shards';
+export type RouteRequest = {
+    tenantId: string;
+    /**
+     * Optional sub-key within a tenant for shardable channels. When set, the
+     * hash key is `${tenantId}:${channelId}`. Use this when a single tenant is
+     * too hot for one engine and its work can be partitioned (e.g. per-doc,
+     * per-room) across multiple engines. Different channels of the same
+     * tenant may land on different shards.
+     */
+    channelId?: string;
+};
+export type RouteResult = {
+    decision: RouteDecision;
+    /** The chosen shard. `null` only when `decision === 'no-shards'`. */
+    shard: Shard | null;
+};
+export type AcquireHandle = {
+    /** Number of active connections for this tenant after acquire (>=1). */
+    active: number;
+    /** Releases one connection for this tenant. Idempotent — safe to call once. */
+    release: () => void;
+};
+export type RouterSnapshot = {
+    shards: Array<Shard & {
+        healthy: boolean;
+        active: number;
+    }>;
+    tenants: number;
+};
+export type Router = {
+    route: (request: RouteRequest) => RouteResult;
+    acquire: (tenantId: string) => AcquireHandle;
+    markHealthy: (shardId: string) => void;
+    markUnhealthy: (shardId: string) => void;
+    addShard: (shard: Shard) => void;
+    removeShard: (shardId: string) => void;
+    shards: () => Shard[];
+    snapshot: () => RouterSnapshot;
+    dispose: () => void;
+};
+export declare const createRouter: (options: RouterOptions) => Router;

package/dist/index.js

@@ -0,0 +1,169 @@
+// @bun
+// src/index.ts
+var fnv1a32 = (input) => {
+  let hash = 2166136261;
+  for (let i = 0;i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+};
+var jumpHash = (key, numBuckets) => {
+  if (numBuckets <= 0)
+    return -1;
+  let k = BigInt(fnv1a32(key)) | BigInt(fnv1a32(key + "#hi")) << 32n;
+  let b = -1n;
+  let j = 0n;
+  while (j < BigInt(numBuckets)) {
+    b = j;
+    k = k * 2862933555777941757n + 1n & 0xffffffffffffffffn;
+    const shifted = (k >> 33n) + 1n;
+    j = (b + 1n) * (1n << 31n) / shifted;
+  }
+  return Number(b);
+};
+var jumpStrategy = (key, shards) => jumpHash(key, shards.length);
+var rendezvousStrategy = (key, shards) => {
+  let bestIndex = 0;
+  let bestScore = -Infinity;
+  for (let i = 0;i < shards.length; i++) {
+    const shard = shards[i];
+    const weight = shard.weight ?? 1;
+    if (weight <= 0)
+      continue;
+    const seed = fnv1a32(`${key}|${shard.id}`);
+    const u = (seed + 1) / 4294967296;
+    const score = weight * -Math.log(u);
+    if (score > bestScore) {
+      bestScore = score;
+      bestIndex = i;
+    }
+  }
+  return bestIndex;
+};
+var resolveStrategy = (strategy) => {
+  if (strategy === "jump")
+    return jumpStrategy;
+  if (strategy === "rendezvous")
+    return rendezvousStrategy;
+  return strategy;
+};
+var createRouter = (options) => {
+  const clock = options.clock ?? Date.now;
+  const strategy = resolveStrategy(options.hashStrategy ?? "jump");
+  const cap = options.perTenantConnectionCap ?? Infinity;
+  const rate = options.perTenantRateLimit ?? { refillPerSecond: 0, tokens: Infinity };
+  const shardList = [...options.shards];
+  const healthy = new Map;
+  for (const shard of shardList)
+    healthy.set(shard.id, true);
+  const tenants = new Map;
+  let disposed = false;
+  const freshTenant = (now) => ({
+    active: 0,
+    lastRefillAt: now,
+    tokens: rate.tokens
+  });
+  const ensureTenant = (id, now) => {
+    const found = tenants.get(id);
+    if (found)
+      return found;
+    const fresh = freshTenant(now);
+    tenants.set(id, fresh);
+    return fresh;
+  };
+  const refill = (state, now) => {
+    if (rate.refillPerSecond <= 0)
+      return;
+    const elapsedMs = now - state.lastRefillAt;
+    if (elapsedMs <= 0)
+      return;
+    const added = elapsedMs / 1000 * rate.refillPerSecond;
+    state.tokens = Math.min(rate.tokens, state.tokens + added);
+    state.lastRefillAt = now;
+  };
+  const healthyShards = () => shardList.filter((shard) => healthy.get(shard.id) === true);
+  const route = (request) => {
+    if (disposed)
+      return { decision: "no-shards", shard: null };
+    const live = healthyShards();
+    if (live.length === 0)
+      return { decision: "no-shards", shard: null };
+    const now = clock();
+    const state = ensureTenant(request.tenantId, now);
+    if (state.active >= cap) {
+      return { decision: "capped", shard: null };
+    }
+    refill(state, now);
+    if (state.tokens < 1) {
+      return { decision: "rate-limited", shard: null };
+    }
+    state.tokens -= 1;
+    const key = request.channelId === undefined ? request.tenantId : `${request.tenantId}:${request.channelId}`;
+    const index = strategy(key, live);
+    const chosen = live[Math.max(0, Math.min(index, live.length - 1))];
+    return { decision: "allow", shard: chosen };
+  };
+  const acquire = (tenantId) => {
+    const now = clock();
+    const state = ensureTenant(tenantId, now);
+    state.active += 1;
+    let released = false;
+    return {
+      active: state.active,
+      release: () => {
+        if (released)
+          return;
+        released = true;
+        const current = tenants.get(tenantId);
+        if (current && current.active > 0)
+          current.active -= 1;
+      }
+    };
+  };
+  return {
+    acquire,
+    addShard: (shard) => {
+      if (shardList.some((existing) => existing.id === shard.id))
+        return;
+      shardList.push(shard);
+      healthy.set(shard.id, true);
+    },
+    dispose: () => {
+      disposed = true;
+      shardList.length = 0;
+      healthy.clear();
+      tenants.clear();
+    },
+    markHealthy: (id) => {
+      if (healthy.has(id))
+        healthy.set(id, true);
+    },
+    markUnhealthy: (id) => {
+      if (healthy.has(id))
+        healthy.set(id, false);
+    },
+    removeShard: (id) => {
+      const at = shardList.findIndex((shard) => shard.id === id);
+      if (at >= 0)
+        shardList.splice(at, 1);
+      healthy.delete(id);
+    },
+    route,
+    shards: () => shardList.map((shard) => ({ ...shard })),
+    snapshot: () => ({
+      shards: shardList.map((shard) => ({
+        ...shard,
+        active: 0,
+        healthy: healthy.get(shard.id) === true
+      })),
+      tenants: tenants.size
+    })
+  };
+};
+export {
+  createRouter
+};
+
+//# debugId=E88C919511EA465E64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * @absolutejs/router — multi-tenant connection routing primitive for Bun PaaS\n * gateways.\n *\n * Sits between an incoming request / WS upgrade and N backend processes (each\n * one a `@absolutejs/runtime` instance hosting a `@absolutejs/sync` engine\n * for a subset of tenants). Decides which shard owns the tenant, whether the\n * tenant is over its rate limit, whether the tenant is over its connection\n * cap, and whether the chosen shard is healthy.\n *\n * v0.0.1 is intentionally bun/elysia-agnostic — pure logic, no `Bun.serve`\n * or proxy code. The caller wires the routing decision into whichever HTTP/WS\n * layer they have. An Elysia adapter ships in a later 0.0.x as a subpath.\n */\n\nexport type Shard = {\n\tid: string;\n\t/**\n\t * Connection target for the chosen backend. Format is opaque to the router\n\t * — `ws://host:port`, `https://host`, a unix socket path, whatever the\n\t * caller's proxy layer understands.\n\t */\n\turl: string;\n\t/**\n\t * Relative weight for hash strategies that support it (rendezvous). Jump\n\t * hash ignores weights — every shard is treated as weight 1. Default 1.\n\t */\n\tweight?: number;\n};\n\n/**\n * Pure hash-strategy function. Given the routing key + the list of currently\n * healthy shards (with their weights), return the index in `shards` of the\n * chosen shard. The router never calls a strategy with an empty `shards`\n * array — that case is handled upstream as `no-shards`.\n */\nexport type HashStrategyFn = (key: string, shards: ReadonlyArray<Shard>) => number;\n\nexport type HashStrategy = 'jump' | 'rendezvous' | HashStrategyFn;\n\n/**\n * Per-tenant token-bucket rate limit. `tokens` is the bucket capacity AND the\n * starting balance; `refillPerSecond` is added continuously up to capacity.\n * Defaults: `Infinity` tokens / `0` refill = no limit.\n */\nexport type RateLimit = {\n\ttokens: number;\n\trefillPerSecond: number;\n};\n\nexport type RouterOptions = {\n\t/** Initial shard set. Can be empty (every `route()` returns `no-shards`). */\n\tshards: Shard[];\n\t/** Hash strategy. Default `'jump'`. */\n\thashStrategy?: HashStrategy;\n\t/**\n\t * Max concurrent connections per tenant (counted via `acquire()` /\n\t * `release()`). Default `Infinity` (no cap). When reached, `route()`\n\t * returns `'capped'`.\n\t */\n\tperTenantConnectionCap?: number;\n\t/**\n\t * Per-tenant token bucket. Default `{ tokens: Infinity, refillPerSecond: 0 }`\n\t * (no limit). When the tenant's bucket is empty, `route()` returns\n\t * `'rate-limited'`. One `route()` call costs one token.\n\t */\n\tperTenantRateLimit?: RateLimit;\n\t/** Override `Date.now` for tests. */\n\tclock?: () => number;\n};\n\nexport type RouteDecision = 'allow' | 'rate-limited' | 'capped' | 'no-shards';\n\nexport type RouteRequest = {\n\ttenantId: string;\n\t/**\n\t * Optional sub-key within a tenant for shardable channels. When set, the\n\t * hash key is `${tenantId}:${channelId}`. Use this when a single tenant is\n\t * too hot for one engine and its work can be partitioned (e.g. per-doc,\n\t * per-room) across multiple engines. Different channels of the same\n\t * tenant may land on different shards.\n\t */\n\tchannelId?: string;\n};\n\nexport type RouteResult = {\n\tdecision: RouteDecision;\n\t/** The chosen shard. `null` only when `decision === 'no-shards'`. */\n\tshard: Shard | null;\n};\n\nexport type AcquireHandle = {\n\t/** Number of active connections for this tenant after acquire (>=1). */\n\tactive: number;\n\t/** Releases one connection for this tenant. Idempotent — safe to call once. */\n\trelease: () => void;\n};\n\nexport type RouterSnapshot = {\n\tshards: Array<Shard & { healthy: boolean; active: number }>;\n\ttenants: number;\n};\n\nexport type Router = {\n\troute: (request: RouteRequest) => RouteResult;\n\tacquire: (tenantId: string) => AcquireHandle;\n\tmarkHealthy: (shardId: string) => void;\n\tmarkUnhealthy: (shardId: string) => void;\n\taddShard: (shard: Shard) => void;\n\tremoveShard: (shardId: string) => void;\n\tshards: () => Shard[];\n\tsnapshot: () => RouterSnapshot;\n\tdispose: () => void;\n};\n\n// -----------------------------------------------------------------------------\n// Hash strategies\n// -----------------------------------------------------------------------------\n\n/**\n * FNV-1a 32-bit. Cheap, no deps, good enough as a seed for the consistent\n * hash strategies below. Not cryptographic — do NOT use as a security hash.\n */\nconst fnv1a32 = (input: string): number => {\n\tlet hash = 0x811c9dc5;\n\tfor (let i = 0; i < input.length; i++) {\n\t\thash ^= input.charCodeAt(i);\n\t\thash = Math.imul(hash, 0x01000193);\n\t}\n\treturn hash >>> 0;\n};\n\n/**\n * Jump-consistent-hash, Lamping & Veach 2014. Maps a 64-bit key to a bucket\n * in `[0, numBuckets)`. Properties: O(log n), no memory, exactly 1/N keys\n * move when buckets are added at the tail. We mix a 32-bit FNV-1a into a\n * 64-bit-ish state via bigint to satisfy the 64-bit arithmetic the algorithm\n * expects.\n */\nconst jumpHash = (key: string, numBuckets: number): number => {\n\tif (numBuckets <= 0) return -1;\n\tlet k = BigInt(fnv1a32(key)) | (BigInt(fnv1a32(key + '#hi')) << 32n);\n\tlet b = -1n;\n\tlet j = 0n;\n\twhile (j < BigInt(numBuckets)) {\n\t\tb = j;\n\t\tk = (k * 2862933555777941757n + 1n) & 0xffffffffffffffffn;\n\t\t// (b + 1) * (1 << 31) / ((k >> 33) + 1)\n\t\tconst shifted = (k >> 33n) + 1n;\n\t\tj = ((b + 1n) * (1n << 31n)) / shifted;\n\t}\n\treturn Number(b);\n};\n\nconst jumpStrategy: HashStrategyFn = (key, shards) => jumpHash(key, shards.length);\n\n/**\n * Rendezvous (highest-random-weight) hash. For each shard, compute\n * `score = weight * -ln(rand(hash(key + shard.id)))`; pick the shard with\n * the highest score. Properties: supports per-shard weighting, single-shard\n * change moves only that shard's \"winning\" keys, O(N) per lookup.\n */\nconst rendezvousStrategy: HashStrategyFn = (key, shards) => {\n\tlet bestIndex = 0;\n\tlet bestScore = -Infinity;\n\tfor (let i = 0; i < shards.length; i++) {\n\t\tconst shard = shards[i]!;\n\t\tconst weight = shard.weight ?? 1;\n\t\tif (weight <= 0) continue;\n\t\tconst seed = fnv1a32(`${key}|${shard.id}`);\n\t\t// Map [0, 2^32) to (0, 1) and take -ln. Heavier weight = higher expected score.\n\t\tconst u = (seed + 1) / 0x1_0000_0000;\n\t\tconst score = weight * -Math.log(u);\n\t\tif (score > bestScore) {\n\t\t\tbestScore = score;\n\t\t\tbestIndex = i;\n\t\t}\n\t}\n\treturn bestIndex;\n};\n\nconst resolveStrategy = (strategy: HashStrategy): HashStrategyFn => {\n\tif (strategy === 'jump') return jumpStrategy;\n\tif (strategy === 'rendezvous') return rendezvousStrategy;\n\treturn strategy;\n};\n\n// -----------------------------------------------------------------------------\n// Router\n// -----------------------------------------------------------------------------\n\ntype TenantState = {\n\tactive: number;\n\ttokens: number;\n\tlastRefillAt: number;\n};\n\nexport const createRouter = (options: RouterOptions): Router => {\n\tconst clock = options.clock ?? Date.now;\n\tconst strategy = resolveStrategy(options.hashStrategy ?? 'jump');\n\tconst cap = options.perTenantConnectionCap ?? Infinity;\n\tconst rate = options.perTenantRateLimit ?? { refillPerSecond: 0, tokens: Infinity };\n\n\tconst shardList: Shard[] = [...options.shards];\n\tconst healthy = new Map<string, boolean>();\n\tfor (const shard of shardList) healthy.set(shard.id, true);\n\n\tconst tenants = new Map<string, TenantState>();\n\tlet disposed = false;\n\n\tconst freshTenant = (now: number): TenantState => ({\n\t\tactive: 0,\n\t\tlastRefillAt: now,\n\t\ttokens: rate.tokens,\n\t});\n\n\tconst ensureTenant = (id: string, now: number): TenantState => {\n\t\tconst found = tenants.get(id);\n\t\tif (found) return found;\n\t\tconst fresh = freshTenant(now);\n\t\ttenants.set(id, fresh);\n\t\treturn fresh;\n\t};\n\n\tconst refill = (state: TenantState, now: number) => {\n\t\tif (rate.refillPerSecond <= 0) return;\n\t\tconst elapsedMs = now - state.lastRefillAt;\n\t\tif (elapsedMs <= 0) return;\n\t\tconst added = (elapsedMs / 1000) * rate.refillPerSecond;\n\t\tstate.tokens = Math.min(rate.tokens, state.tokens + added);\n\t\tstate.lastRefillAt = now;\n\t};\n\n\tconst healthyShards = (): Shard[] => shardList.filter((shard) => healthy.get(shard.id) === true);\n\n\tconst route: Router['route'] = (request) => {\n\t\tif (disposed) return { decision: 'no-shards', shard: null };\n\n\t\tconst live = healthyShards();\n\t\tif (live.length === 0) return { decision: 'no-shards', shard: null };\n\n\t\tconst now = clock();\n\t\tconst state = ensureTenant(request.tenantId, now);\n\n\t\tif (state.active >= cap) {\n\t\t\treturn { decision: 'capped', shard: null };\n\t\t}\n\n\t\trefill(state, now);\n\t\tif (state.tokens < 1) {\n\t\t\treturn { decision: 'rate-limited', shard: null };\n\t\t}\n\t\tstate.tokens -= 1;\n\n\t\tconst key = request.channelId === undefined\n\t\t\t? request.tenantId\n\t\t\t: `${request.tenantId}:${request.channelId}`;\n\t\tconst index = strategy(key, live);\n\t\tconst chosen = live[Math.max(0, Math.min(index, live.length - 1))]!;\n\t\treturn { decision: 'allow', shard: chosen };\n\t};\n\n\tconst acquire: Router['acquire'] = (tenantId) => {\n\t\tconst now = clock();\n\t\tconst state = ensureTenant(tenantId, now);\n\t\tstate.active += 1;\n\t\tlet released = false;\n\t\treturn {\n\t\t\tactive: state.active,\n\t\t\trelease: () => {\n\t\t\t\tif (released) return;\n\t\t\t\treleased = true;\n\t\t\t\tconst current = tenants.get(tenantId);\n\t\t\t\tif (current && current.active > 0) current.active -= 1;\n\t\t\t},\n\t\t};\n\t};\n\n\treturn {\n\t\tacquire,\n\t\taddShard: (shard) => {\n\t\t\tif (shardList.some((existing) => existing.id === shard.id)) return;\n\t\t\tshardList.push(shard);\n\t\t\thealthy.set(shard.id, true);\n\t\t},\n\t\tdispose: () => {\n\t\t\tdisposed = true;\n\t\t\tshardList.length = 0;\n\t\t\thealthy.clear();\n\t\t\ttenants.clear();\n\t\t},\n\t\tmarkHealthy: (id) => {\n\t\t\tif (healthy.has(id)) healthy.set(id, true);\n\t\t},\n\t\tmarkUnhealthy: (id) => {\n\t\t\tif (healthy.has(id)) healthy.set(id, false);\n\t\t},\n\t\tremoveShard: (id) => {\n\t\t\tconst at = shardList.findIndex((shard) => shard.id === id);\n\t\t\tif (at >= 0) shardList.splice(at, 1);\n\t\t\thealthy.delete(id);\n\t\t},\n\t\troute,\n\t\tshards: () => shardList.map((shard) => ({ ...shard })),\n\t\tsnapshot: () => ({\n\t\t\tshards: shardList.map((shard) => ({\n\t\t\t\t...shard,\n\t\t\t\tactive: 0,\n\t\t\t\thealthy: healthy.get(shard.id) === true,\n\t\t\t})),\n\t\t\ttenants: tenants.size,\n\t\t}),\n\t};\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "E88C919511EA465E64756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@absolutejs/router",
+  "version": "0.0.1",
+  "description": "Multi-tenant connection routing primitive for Bun PaaS gateways. Consistent-hash tenant→shard, per-tenant connection cap, per-tenant rate limit, healthy-shard skip. The library that goes in front of N @absolutejs/runtime instances.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/absolutejs/router.git"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "license": "BSL-1.1",
+  "author": "Alex Kahn",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "absolutejs",
+    "bun",
+    "paas",
+    "multi-tenant",
+    "router",
+    "consistent-hash",
+    "rate-limit",
+    "websocket"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --sourcemap --target=bun && tsc --project tsconfig.build.json",
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"./**/*.{ts,json,md}\"",
+    "check:package": "bun run typecheck && bun run build && bun run test",
+    "release": "bun run format && bun run check:package && bun publish"
+  },
+  "peerDependencies": {
+    "bun-types": "^1.3.14"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"]
+}