@fireweaveai/server-sdk-cjs 0.0.0-reserve.0

package/dist/start/state.js

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.slot = slot;
+exports.warnOnce = warnOnce;
+exports.start = start;
+exports.startWith = startWith;
+exports.ensureClient = ensureClient;
+exports.currentStatus = currentStatus;
+exports.instanceKeyFor = instanceKeyFor;
+exports.shutdownSlot = shutdownSlot;
+exports.resetForTests = resetForTests;
+/**
+ * start() and the process-wide singleton behind `fw`.
+ *
+ * One slot per process (or worker thread) at a Symbol.for key on globalThis,
+ * so two bundled copies of this package share one client. start() is
+ * synchronous: it resolves and validates everything up front, throws a
+ * Configuration error for bad config, then hands off to the unchanged core
+ * initFireweave(). Reads await readiness and never throw.
+ *
+ * A read that happens before any start() schedules an env-only start on the
+ * next macrotask. An ES module graph without top-level await evaluates in one
+ * job, so an entrypoint that imports ./fireweave/start first always wins.
+ */
+const index_js_1 = require("../index.js");
+const build_info_js_1 = require("./build-info.js");
+const env_js_1 = require("./env.js");
+const control_points_js_1 = require("./control-points.js");
+const instance_js_1 = require("./instance.js");
+const resolve_js_1 = require("./resolve.js");
+const deferred = () => {
+    let resolve;
+    const promise = new Promise((r) => {
+        resolve = r;
+    });
+    return { promise, resolve };
+};
+const SLOT_KEY = Symbol.for('@fireweaveai/server-sdk/start');
+const defaultLog = (line) => {
+    if (line.startsWith('[fireweave:local]'))
+        console.info(line);
+    else
+        console.warn(line);
+};
+const freshSlot = () => ({
+    protocol: 1,
+    state: 'unstarted',
+    implicit: false,
+    ready: deferred(),
+    implicitScheduled: false,
+    log: defaultLog,
+    warned: new Set(),
+    diagnosed: new Set(),
+});
+function slot() {
+    const g = globalThis;
+    const existing = g[SLOT_KEY];
+    if (existing !== undefined) {
+        if (existing.protocol !== 1) {
+            throw new index_js_1.FireweaveError('Configuration', {
+                message: '[fireweave] Two incompatible copies of @fireweaveai/server-sdk are loaded. Deduplicate the dependency.',
+            });
+        }
+        return existing;
+    }
+    const created = freshSlot();
+    g[SLOT_KEY] = created;
+    return created;
+}
+function warnOnce(s, line) {
+    if (s.warned.has(line))
+        return;
+    s.warned.add(line);
+    s.log(line);
+}
+const signatureOf = (r, instanceId) => (0, index_js_1.stableStringify)({
+    mode: r.mode,
+    url: r.url ?? null,
+    key: r.key ?? null,
+    allowedHosts: r.allowedHosts !== undefined ? [...r.allowedHosts] : null,
+    instanceId: instanceId ?? null,
+    // Seeds only matter in local mode; remote ignores them, so an env-only
+    // implicit start followed by start({ controlPoints }) under a key is not a conflict.
+    ...(r.mode === 'local' ? { controlPoints: (0, control_points_js_1.toLocalControlPoints)(r.controlPoints) } : {}),
+});
+function localLine(r) {
+    const why = r.modeSource === 'option'
+        ? "start({ mode: 'local' })"
+        : `no FIREWEAVE_KEY; environment '${r.environment ?? ''}' from ${r.environmentSource ?? 'env'}`;
+    const n = Object.keys(r.controlPoints).length;
+    return `[fireweave:local] Local mode (${why}). Serving ${n} control point${n === 1 ? '' : 's'} from your control-points object; nothing is sent to fw-server.`;
+}
+/** The kind the core's remote adapter reports for an HTTP status, or undefined for a success. */
+function kindForStatus(status) {
+    if (status < 400)
+        return undefined;
+    if (status === 401)
+        return 'Authentication';
+    if (status === 403)
+        return 'Authorization';
+    if (status === 429)
+        return 'RateLimited';
+    return 'BackendUnavailable';
+}
+/**
+ * SP-27: a refused key, a rate limit or an unreachable fw-server is logged
+ * once per group for the life of the process and kept as lastErrorKind, so a
+ * revoked key does not look like a rollout at 0%. Lines name the key's source
+ * and the host, never the key.
+ */
+function observeFailure(s, token, r, kind, detail) {
+    if (s.ready !== token)
+        return; // a response for a client that was shut down or replaced
+    s.lastErrorKind = kind;
+    const host = r.url !== undefined ? new URL(r.url).host : 'fw-server';
+    let group;
+    let line;
+    switch (kind) {
+        case 'Authentication':
+            group = 'key-rejected-401';
+            line = `[fireweave] fw-server at ${host} rejected the key from ${r.keySource} (HTTP 401): it is wrong, revoked or from another project. Reads serve their defaults; this is not a rollout at 0%.`;
+            break;
+        case 'Authorization':
+            group = 'key-rejected-403';
+            line = `[fireweave] fw-server at ${host} refused the key from ${r.keySource} for this project or environment (HTTP 403). Reads serve their defaults; this is not a rollout at 0%.`;
+            break;
+        case 'RateLimited':
+            group = 'rate-limited';
+            line = `[fireweave] fw-server at ${host} rate-limited the key from ${r.keySource} (HTTP 429). Reads serve their defaults until a request succeeds.`;
+            break;
+        default:
+            group = 'unreachable';
+            line = `[fireweave] Could not reach fw-server at ${host} (endpoint from ${r.urlSource ?? 'the SDK channel'}; ${detail}): offline, a firewall, or the wrong endpoint. Reads serve their defaults until a request succeeds.`;
+    }
+    if (s.diagnosed.has(group))
+        return;
+    s.diagnosed.add(group);
+    try {
+        s.log(line);
+    }
+    catch {
+        // A faulty log sink must not turn into a transport failure.
+    }
+}
+/** The transport handed to the core, observed. The core's behaviour is unchanged. */
+function observedTransport(s, token, r, base) {
+    return async (url, init) => {
+        const call = base ?? globalThis.fetch;
+        let response;
+        try {
+            response = await call(url, init);
+        }
+        catch (err) {
+            // The same split the core makes: its own deadline aborts the request.
+            const timedOut = err instanceof Error && err.name === 'AbortError';
+            observeFailure(s, token, r, timedOut ? 'Timeout' : 'Network', timedOut ? 'timed out' : 'network error');
+            throw err;
+        }
+        const kind = kindForStatus(response.status);
+        if (kind !== undefined)
+            observeFailure(s, token, r, kind, `HTTP ${response.status}`);
+        return response;
+    };
+}
+function initOptions(r, options, s, token) {
+    if (r.mode === 'local') {
+        return { mode: 'local', local: { controlPoints: (0, control_points_js_1.toLocalControlPoints)(r.controlPoints), log: (line) => s.log(line) } };
+    }
+    return {
+        mode: 'remote',
+        apiKey: r.key,
+        apiUrl: r.url,
+        ...(r.allowedHosts !== undefined ? { allowedHosts: r.allowedHosts } : {}),
+        fetch: observedTransport(s, token, r, options.fetch),
+    };
+}
+/** Start FireWeave for this process. Synchronous; call once, from src/fireweave/start.ts. */
+function start(options = {}) {
+    startWith(options, false);
+}
+function startWith(options, implicit) {
+    const s = slot();
+    if (s.state === 'shutdown' || s.state === 'failed') {
+        // Warnings and fw-server failure lines are once per process, across restarts.
+        Object.assign(s, freshSlot(), { warned: s.warned, diagnosed: s.diagnosed });
+        delete s.lastErrorKind; // freshSlot() has no such key, so assign alone would keep it
+    }
+    const read = options.env !== undefined ? (0, env_js_1.envFromBag)(options.env) : (0, env_js_1.processEnv)();
+    const resolved = (0, resolve_js_1.resolveStart)(options, read, { version: build_info_js_1.SDK_VERSION, channel: build_info_js_1.SDK_CHANNEL });
+    const signature = signatureOf(resolved, options.instanceId);
+    if (s.state === 'starting' || s.state === 'ready') {
+        if (signature === s.signature)
+            return;
+        throw new index_js_1.FireweaveError('Configuration', {
+            message: s.implicit
+                ? "[fireweave] A control point was read before start() ran, so FireWeave started from the environment alone. Import './fireweave/start' as the first import of your entrypoint."
+                : '[fireweave] start() was already called with a different configuration. Call start() once, from src/fireweave/start.ts.',
+        });
+    }
+    if (options.instanceId !== undefined && s.instance !== undefined && s.instance.value !== options.instanceId) {
+        throw new index_js_1.FireweaveError('Configuration', {
+            message: '[fireweave] start({ instanceId }) differs from the instanceKey() already handed out. Pass instanceId on the first start().',
+        });
+    }
+    // Only a start that actually begins sets the log sink: an identical second
+    // start() is a no-op and a conflicting one throws, and neither may swap it.
+    if (!implicit && options.log !== undefined)
+        s.log = options.log;
+    s.state = 'starting';
+    s.signature = signature;
+    s.implicit = implicit;
+    s.resolved = resolved;
+    s.read = read;
+    if (options.instanceId !== undefined)
+        s.instanceIdOption = options.instanceId;
+    for (const w of resolved.warnings)
+        warnOnce(s, w);
+    if (resolved.mode === 'local')
+        s.log(localLine(resolved));
+    const ready = s.ready;
+    const pending = (0, index_js_1.initFireweave)(initOptions(resolved, options, s, ready)).then((client) => {
+        if (s.ready !== ready)
+            return undefined; // superseded by shutdown/restart
+        s.state = 'ready';
+        s.client = client;
+        return client;
+    }, (err) => {
+        if (s.ready !== ready)
+            return undefined;
+        s.state = 'failed';
+        s.error = (0, index_js_1.isFireweaveError)(err) ? err : new index_js_1.FireweaveError('Internal', { cause: err });
+        warnOnce(s, `[fireweave] start failed: ${s.error.message}. Reads serve their defaults.`);
+        return undefined;
+    });
+    ready.resolve(pending);
+}
+/** The client once start() settles; undefined when start failed. Schedules an implicit start if none ran. */
+function ensureClient() {
+    const s = slot();
+    if (s.state === 'unstarted' && !s.implicitScheduled) {
+        s.implicitScheduled = true;
+        setTimeout(() => {
+            if (s.state !== 'unstarted')
+                return;
+            try {
+                startWith({}, true);
+            }
+            catch (err) {
+                s.state = 'failed';
+                s.error = (0, index_js_1.isFireweaveError)(err) ? err : new index_js_1.FireweaveError('Internal', { cause: err });
+                warnOnce(s, `${s.error.message} (FireWeave was not started; reads serve their defaults.)`);
+                s.ready.resolve(undefined);
+            }
+        }, 0);
+    }
+    return s.ready.promise;
+}
+function currentStatus() {
+    const s = slot();
+    const r = s.resolved;
+    return {
+        state: s.state,
+        channel: r?.channel ?? build_info_js_1.SDK_CHANNEL,
+        sdkVersion: r?.sdkVersion ?? build_info_js_1.SDK_VERSION,
+        ...(r !== undefined
+            ? {
+                mode: r.mode,
+                modeSource: r.modeSource,
+                keySource: r.keySource,
+                controlPointCount: Object.keys(r.controlPoints).length,
+                ...(r.url !== undefined ? { host: new URL(r.url).hostname, endpointSource: r.urlSource } : {}),
+                ...(r.environment !== undefined ? { environment: r.environment } : {}),
+            }
+            : {}),
+        ...(s.error !== undefined ? { error: s.error.message } : {}),
+        ...(s.lastErrorKind !== undefined ? { lastErrorKind: s.lastErrorKind } : {}),
+    };
+}
+function instanceKeyFor() {
+    const s = slot();
+    if (s.instance === undefined)
+        s.instance = (0, instance_js_1.deriveInstanceKey)(s.instanceIdOption, s.read ?? (0, env_js_1.processEnv)());
+    return s.instance.value;
+}
+async function shutdownSlot() {
+    const s = slot();
+    const client = s.state === 'starting' ? await s.ready.promise : s.client;
+    s.state = 'shutdown';
+    s.client = undefined;
+    s.ready = deferred();
+    s.ready.resolve(undefined);
+    s.implicitScheduled = true; // no implicit restart after an explicit shutdown
+    if (client !== undefined)
+        await client.shutdown();
+}
+/** Test only: shut down and forget the singleton so the next start() begins fresh. */
+async function resetForTests() {
+    const g = globalThis;
+    const s = g[SLOT_KEY];
+    if (s?.client !== undefined)
+        await s.client.shutdown().catch(() => undefined);
+    delete g[SLOT_KEY];
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@fireweaveai/server-sdk-cjs",
+  "version": "0.0.0-reserve.0",
+  "description": "CommonJS build of @fireweaveai/server-sdk, for require() and toolchains without ESM support. Fireweave release-engineering SDK for server runtimes (Node, Bun, Deno): control points and target registration. Zero runtime dependencies (spec v0.1.0).",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FireWeave-HQ/fireweave-sdk.git",
+    "directory": "sdks/node"
+  },
+  "homepage": "https://github.com/FireWeave-HQ/fireweave-sdk/tree/master/sdks/node#readme",
+  "bugs": "https://github.com/FireWeave-HQ/fireweave-sdk/issues",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "start": [
+        "./dist/start/index.d.ts"
+      ],
+      "register": [
+        "./dist/register.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./start": {
+      "types": "./dist/start/index.d.ts",
+      "browser": "./dist/start/browser.js",
+      "default": "./dist/start/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "browser": "./dist/register-browser.js",
+      "default": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "fireweave",
+    "release-engineering",
+    "progressive-delivery",
+    "control-points",
+    "feature-flags",
+    "server",
+    "bun",
+    "deno"
+  ]
+}