@fireweaveai/server-sdk 2.2.1-staging.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +263 -0
- package/dist/application/client.d.ts +92 -0
- package/dist/application/client.d.ts.map +1 -0
- package/dist/application/client.js +156 -0
- package/dist/application/client.js.map +1 -0
- package/dist/application/mode.d.ts +71 -0
- package/dist/application/mode.d.ts.map +1 -0
- package/dist/application/mode.js +72 -0
- package/dist/application/mode.js.map +1 -0
- package/dist/application/ports.d.ts +95 -0
- package/dist/application/ports.d.ts.map +1 -0
- package/dist/application/ports.js +2 -0
- package/dist/application/ports.js.map +1 -0
- package/dist/application/runtime.d.ts +102 -0
- package/dist/application/runtime.d.ts.map +1 -0
- package/dist/application/runtime.js +342 -0
- package/dist/application/runtime.js.map +1 -0
- package/dist/domain/context.d.ts +68 -0
- package/dist/domain/context.d.ts.map +1 -0
- package/dist/domain/context.js +85 -0
- package/dist/domain/context.js.map +1 -0
- package/dist/domain/errors.d.ts +43 -0
- package/dist/domain/errors.d.ts.map +1 -0
- package/dist/domain/errors.js +64 -0
- package/dist/domain/errors.js.map +1 -0
- package/dist/domain/target.d.ts +3 -0
- package/dist/domain/target.d.ts.map +1 -0
- package/dist/domain/target.js +2 -0
- package/dist/domain/target.js.map +1 -0
- package/dist/domain/types.d.ts +108 -0
- package/dist/domain/types.d.ts.map +1 -0
- package/dist/domain/types.js +2 -0
- package/dist/domain/types.js.map +1 -0
- package/dist/domain/validation.d.ts +125 -0
- package/dist/domain/validation.d.ts.map +1 -0
- package/dist/domain/validation.js +347 -0
- package/dist/domain/validation.js.map +1 -0
- package/dist/index.d.ts +35 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +23 -0
- package/dist/index.js.map +1 -0
- package/dist/infrastructure/adapters/inmemory.d.ts +78 -0
- package/dist/infrastructure/adapters/inmemory.d.ts.map +1 -0
- package/dist/infrastructure/adapters/inmemory.js +148 -0
- package/dist/infrastructure/adapters/inmemory.js.map +1 -0
- package/dist/infrastructure/adapters/local.d.ts +109 -0
- package/dist/infrastructure/adapters/local.d.ts.map +1 -0
- package/dist/infrastructure/adapters/local.js +102 -0
- package/dist/infrastructure/adapters/local.js.map +1 -0
- package/dist/infrastructure/adapters/remote.d.ts +75 -0
- package/dist/infrastructure/adapters/remote.d.ts.map +1 -0
- package/dist/infrastructure/adapters/remote.js +361 -0
- package/dist/infrastructure/adapters/remote.js.map +1 -0
- package/dist/infrastructure/hosts.d.ts +19 -0
- package/dist/infrastructure/hosts.d.ts.map +1 -0
- package/dist/infrastructure/hosts.js +68 -0
- package/dist/infrastructure/hosts.js.map +1 -0
- package/package.json +56 -0
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Evaluation-context handling: merge order (global → client → invocation)
|
|
3
|
+
* and normalization of raw caller input into the shape validation.ts checks,
|
|
4
|
+
* plus the post-canonicalization reporting view.
|
|
5
|
+
* Bounds per spec/evaluation-context.schema.json (ratified 2026-07-27):
|
|
6
|
+
* 128 attrs / 256 B keys / 4 KiB values / depth 6 / 64 KiB serialized.
|
|
7
|
+
*
|
|
8
|
+
* Bound/reserved-key ENFORCEMENT (the pure, Validated<T>-returning checks)
|
|
9
|
+
* lives in validation.ts (`validateContext`) — spec/control-points.md
|
|
10
|
+
* "Validation, before any I/O" rule 3. This module has no throwing/failing
|
|
11
|
+
* surface of its own.
|
|
12
|
+
*/
|
|
13
|
+
import type { CanonicalContext, JsonValue } from './types.js';
|
|
14
|
+
export interface ContextLimits {
|
|
15
|
+
maxAttributeCount: number;
|
|
16
|
+
maxKeyBytes: number;
|
|
17
|
+
maxValueBytes: number;
|
|
18
|
+
maxNestingDepth: number;
|
|
19
|
+
maxSerializedContextBytes: number;
|
|
20
|
+
}
|
|
21
|
+
export declare const DEFAULT_CONTEXT_LIMITS: Readonly<ContextLimits>;
|
|
22
|
+
/** Attribute keys callers may never set (in addition to the fireweave.* namespace). */
|
|
23
|
+
export declare const DEFAULT_RESERVED_ATTRIBUTE_KEYS: readonly string[];
|
|
24
|
+
/**
|
|
25
|
+
* Sanctioned fireweave.* carriers (orchestrator rulings 12–14): the ONLY
|
|
26
|
+
* `fireweave.*` context keys callers may set. They are the canonical spelling
|
|
27
|
+
* for group memberships / group properties; plain `groups`/`groupProperties`
|
|
28
|
+
* remain accepted as a documented alias.
|
|
29
|
+
*/
|
|
30
|
+
export declare const ALLOWED_FIREWEAVE_CONTEXT_KEYS: readonly string[];
|
|
31
|
+
export interface ContextPolicy {
|
|
32
|
+
limits: ContextLimits;
|
|
33
|
+
reservedAttributeKeys: readonly string[];
|
|
34
|
+
requireTargetingKey: boolean;
|
|
35
|
+
}
|
|
36
|
+
/** Loose input shape accepted from callers (OpenFeature EvaluationContext-compatible). */
|
|
37
|
+
export interface ContextInput {
|
|
38
|
+
targetingKey?: string;
|
|
39
|
+
attributes?: Record<string, unknown>;
|
|
40
|
+
/** OpenFeature flat contexts: extra top-level keys are treated as attributes. */
|
|
41
|
+
[key: string]: unknown;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Extract {targetingKey, attributes} from a caller context. Supports both the
|
|
45
|
+
* canonical shape ({targetingKey, attributes:{...}}) and OpenFeature flat shape
|
|
46
|
+
* ({targetingKey, plan:"pro", ...}).
|
|
47
|
+
*/
|
|
48
|
+
export declare function normalizeContextInput(input: ContextInput | undefined): {
|
|
49
|
+
targetingKey?: string;
|
|
50
|
+
attributes: Record<string, unknown>;
|
|
51
|
+
};
|
|
52
|
+
/**
|
|
53
|
+
* Merge context layers with later layers winning at the attribute-key level.
|
|
54
|
+
* Layers are raw inputs; output is a deep copy (caller objects never retained).
|
|
55
|
+
*/
|
|
56
|
+
export declare function mergeContexts(...layers: Array<ContextInput | undefined>): {
|
|
57
|
+
targetingKey?: string;
|
|
58
|
+
attributes: Record<string, unknown>;
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* Resolved context for reporting/telemetry: `$`-prefixed system directives are
|
|
62
|
+
* filtered out; empty attributes omitted.
|
|
63
|
+
*/
|
|
64
|
+
export declare function resolvedContextView(ctx: CanonicalContext): {
|
|
65
|
+
targetingKey?: string;
|
|
66
|
+
attributes?: Record<string, JsonValue>;
|
|
67
|
+
};
|
|
68
|
+
//# sourceMappingURL=context.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/domain/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,aAAa,CAMzD,CAAC;AAEH,uFAAuF;AACvF,eAAO,MAAM,+BAA+B,EAAE,SAAS,MAAM,EAG3D,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAG1D,CAAC;AAEH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,iFAAiF;IACjF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC,CAiBA;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC,CAWA;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,GAAG;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACxC,CAUA"}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
export const DEFAULT_CONTEXT_LIMITS = Object.freeze({
|
|
2
|
+
maxAttributeCount: 128,
|
|
3
|
+
maxKeyBytes: 256,
|
|
4
|
+
maxValueBytes: 4096,
|
|
5
|
+
maxNestingDepth: 6,
|
|
6
|
+
maxSerializedContextBytes: 65536,
|
|
7
|
+
});
|
|
8
|
+
/** Attribute keys callers may never set (in addition to the fireweave.* namespace). */
|
|
9
|
+
export const DEFAULT_RESERVED_ATTRIBUTE_KEYS = Object.freeze([
|
|
10
|
+
'targetingKey',
|
|
11
|
+
'kind',
|
|
12
|
+
]);
|
|
13
|
+
/**
|
|
14
|
+
* Sanctioned fireweave.* carriers (orchestrator rulings 12–14): the ONLY
|
|
15
|
+
* `fireweave.*` context keys callers may set. They are the canonical spelling
|
|
16
|
+
* for group memberships / group properties; plain `groups`/`groupProperties`
|
|
17
|
+
* remain accepted as a documented alias.
|
|
18
|
+
*/
|
|
19
|
+
export const ALLOWED_FIREWEAVE_CONTEXT_KEYS = Object.freeze([
|
|
20
|
+
'fireweave.groups',
|
|
21
|
+
'fireweave.groupProperties',
|
|
22
|
+
]);
|
|
23
|
+
/**
|
|
24
|
+
* Extract {targetingKey, attributes} from a caller context. Supports both the
|
|
25
|
+
* canonical shape ({targetingKey, attributes:{...}}) and OpenFeature flat shape
|
|
26
|
+
* ({targetingKey, plan:"pro", ...}).
|
|
27
|
+
*/
|
|
28
|
+
export function normalizeContextInput(input) {
|
|
29
|
+
if (input === undefined || input === null)
|
|
30
|
+
return { attributes: {} };
|
|
31
|
+
const attributes = {};
|
|
32
|
+
let targetingKey;
|
|
33
|
+
if (typeof input.targetingKey === 'string' && input.targetingKey.length > 0) {
|
|
34
|
+
targetingKey = input.targetingKey;
|
|
35
|
+
}
|
|
36
|
+
if (input.attributes !== undefined && typeof input.attributes === 'object' && input.attributes !== null && !Array.isArray(input.attributes)) {
|
|
37
|
+
for (const [k, v] of Object.entries(input.attributes)) {
|
|
38
|
+
if (v !== undefined)
|
|
39
|
+
attributes[k] = v;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
for (const [k, v] of Object.entries(input)) {
|
|
43
|
+
if (k === 'targetingKey' || k === 'attributes')
|
|
44
|
+
continue;
|
|
45
|
+
if (v !== undefined)
|
|
46
|
+
attributes[k] = v;
|
|
47
|
+
}
|
|
48
|
+
return targetingKey !== undefined ? { targetingKey, attributes } : { attributes };
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Merge context layers with later layers winning at the attribute-key level.
|
|
52
|
+
* Layers are raw inputs; output is a deep copy (caller objects never retained).
|
|
53
|
+
*/
|
|
54
|
+
export function mergeContexts(...layers) {
|
|
55
|
+
let targetingKey;
|
|
56
|
+
const attributes = {};
|
|
57
|
+
for (const layer of layers) {
|
|
58
|
+
const { targetingKey: tk, attributes: attrs } = normalizeContextInput(layer);
|
|
59
|
+
if (tk !== undefined)
|
|
60
|
+
targetingKey = tk;
|
|
61
|
+
for (const [k, v] of Object.entries(attrs)) {
|
|
62
|
+
attributes[k] = v;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
return targetingKey !== undefined ? { targetingKey, attributes } : { attributes };
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Resolved context for reporting/telemetry: `$`-prefixed system directives are
|
|
69
|
+
* filtered out; empty attributes omitted.
|
|
70
|
+
*/
|
|
71
|
+
export function resolvedContextView(ctx) {
|
|
72
|
+
const attributes = {};
|
|
73
|
+
for (const [k, v] of Object.entries(ctx.attributes)) {
|
|
74
|
+
if (k.startsWith('$'))
|
|
75
|
+
continue;
|
|
76
|
+
attributes[k] = v;
|
|
77
|
+
}
|
|
78
|
+
const out = {};
|
|
79
|
+
if (ctx.targetingKey !== undefined)
|
|
80
|
+
out.targetingKey = ctx.targetingKey;
|
|
81
|
+
if (Object.keys(attributes).length > 0)
|
|
82
|
+
out.attributes = attributes;
|
|
83
|
+
return out;
|
|
84
|
+
}
|
|
85
|
+
//# sourceMappingURL=context.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/domain/context.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fireweave canonical error taxonomy (spec/errors.schema.json, contracts/errors.json).
|
|
3
|
+
*
|
|
4
|
+
* 15 PascalCase kinds mapped to OpenFeature error codes. Rules:
|
|
5
|
+
* - defaults never throw: evaluation paths surface errors via Decision, not exceptions;
|
|
6
|
+
* - no secrets in messages: all outward-facing messages are redacted;
|
|
7
|
+
* - cause preserved internally (`FireweaveError.cause`), never serialized outward.
|
|
8
|
+
*/
|
|
9
|
+
export type FireweaveErrorKind = 'NotReady' | 'FlagNotFound' | 'TypeMismatch' | 'InvalidContext' | 'Authentication' | 'Authorization' | 'RateLimited' | 'Timeout' | 'Network' | 'BackendUnavailable' | 'MalformedResponse' | 'UnsupportedCapability' | 'Configuration' | 'AlreadyClosed' | 'Internal';
|
|
10
|
+
/** OpenFeature error code strings (mirrors @openfeature/core ErrorCode values). */
|
|
11
|
+
export type OpenFeatureErrorCode = 'PROVIDER_NOT_READY' | 'PROVIDER_FATAL' | 'FLAG_NOT_FOUND' | 'PARSE_ERROR' | 'TYPE_MISMATCH' | 'TARGETING_KEY_MISSING' | 'INVALID_CONTEXT' | 'GENERAL';
|
|
12
|
+
export interface ErrorKindSpec {
|
|
13
|
+
readonly kind: FireweaveErrorKind;
|
|
14
|
+
readonly openFeatureErrorCode: OpenFeatureErrorCode;
|
|
15
|
+
readonly retryable: boolean;
|
|
16
|
+
readonly errorClass: 'transient' | 'permanent';
|
|
17
|
+
readonly defaultMessage: string;
|
|
18
|
+
}
|
|
19
|
+
export declare const ERROR_TAXONOMY: Readonly<Record<FireweaveErrorKind, ErrorKindSpec>>;
|
|
20
|
+
/** Redact secret-shaped substrings; collapse whitespace runs; trim. */
|
|
21
|
+
export declare function redactSecrets(text: string): string;
|
|
22
|
+
export interface FireweaveErrorOptions {
|
|
23
|
+
/** Custom message; will be redacted. Defaults to the taxonomy default message. */
|
|
24
|
+
message?: string;
|
|
25
|
+
/** Underlying cause, preserved internally only. */
|
|
26
|
+
cause?: unknown;
|
|
27
|
+
/** Override the OF code (e.g. TARGETING_KEY_MISSING for InvalidContext). */
|
|
28
|
+
openFeatureErrorCode?: OpenFeatureErrorCode;
|
|
29
|
+
/** Extra fireweave.* flag metadata to surface with error decisions. */
|
|
30
|
+
metadata?: Record<string, string | number | boolean>;
|
|
31
|
+
}
|
|
32
|
+
export declare class FireweaveError extends Error {
|
|
33
|
+
readonly kind: FireweaveErrorKind;
|
|
34
|
+
readonly openFeatureErrorCode: OpenFeatureErrorCode;
|
|
35
|
+
readonly retryable: boolean;
|
|
36
|
+
readonly errorClass: 'transient' | 'permanent';
|
|
37
|
+
/** Deterministic outward-facing message from the taxonomy. */
|
|
38
|
+
readonly safeMessage: string;
|
|
39
|
+
readonly metadata: Readonly<Record<string, string | number | boolean>>;
|
|
40
|
+
constructor(kind: FireweaveErrorKind, options?: FireweaveErrorOptions);
|
|
41
|
+
}
|
|
42
|
+
export declare function isFireweaveError(err: unknown): err is FireweaveError;
|
|
43
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/domain/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,GACf,aAAa,GACb,SAAS,GACT,SAAS,GACT,oBAAoB,GACpB,mBAAmB,GACnB,uBAAuB,GACvB,eAAe,GACf,eAAe,GACf,UAAU,CAAC;AAEf,mFAAmF;AACnF,MAAM,MAAM,oBAAoB,GAC5B,oBAAoB,GACpB,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,GACb,eAAe,GACf,uBAAuB,GACvB,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,WAAW,GAAG,WAAW,CAAC;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAUD,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAgB7E,CAAC;AAQH,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACtD;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,WAAW,GAAG,WAAW,CAAC;IAC/C,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;gBAE3D,IAAI,EAAE,kBAAkB,EAAE,OAAO,GAAE,qBAA0B;CAY1E;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAEpE"}
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fireweave canonical error taxonomy (spec/errors.schema.json, contracts/errors.json).
|
|
3
|
+
*
|
|
4
|
+
* 15 PascalCase kinds mapped to OpenFeature error codes. Rules:
|
|
5
|
+
* - defaults never throw: evaluation paths surface errors via Decision, not exceptions;
|
|
6
|
+
* - no secrets in messages: all outward-facing messages are redacted;
|
|
7
|
+
* - cause preserved internally (`FireweaveError.cause`), never serialized outward.
|
|
8
|
+
*/
|
|
9
|
+
const spec = (kind, openFeatureErrorCode, retryable, errorClass, defaultMessage) => ({ kind, openFeatureErrorCode, retryable, errorClass, defaultMessage });
|
|
10
|
+
export const ERROR_TAXONOMY = Object.freeze({
|
|
11
|
+
NotReady: spec('NotReady', 'PROVIDER_NOT_READY', true, 'transient', 'provider not ready'),
|
|
12
|
+
FlagNotFound: spec('FlagNotFound', 'FLAG_NOT_FOUND', false, 'permanent', 'flag not found'),
|
|
13
|
+
TypeMismatch: spec('TypeMismatch', 'TYPE_MISMATCH', false, 'permanent', 'flag type mismatch'),
|
|
14
|
+
InvalidContext: spec('InvalidContext', 'INVALID_CONTEXT', false, 'permanent', 'invalid evaluation context'),
|
|
15
|
+
Authentication: spec('Authentication', 'GENERAL', false, 'permanent', 'authentication failed'),
|
|
16
|
+
Authorization: spec('Authorization', 'GENERAL', false, 'permanent', 'authorization failed'),
|
|
17
|
+
RateLimited: spec('RateLimited', 'GENERAL', true, 'transient', 'rate limited'),
|
|
18
|
+
Timeout: spec('Timeout', 'GENERAL', true, 'transient', 'request timed out'),
|
|
19
|
+
Network: spec('Network', 'GENERAL', true, 'transient', 'network error'),
|
|
20
|
+
BackendUnavailable: spec('BackendUnavailable', 'GENERAL', true, 'transient', 'backend unavailable'),
|
|
21
|
+
MalformedResponse: spec('MalformedResponse', 'PARSE_ERROR', false, 'permanent', 'malformed backend response'),
|
|
22
|
+
UnsupportedCapability: spec('UnsupportedCapability', 'GENERAL', false, 'permanent', 'unsupported capability'),
|
|
23
|
+
Configuration: spec('Configuration', 'PROVIDER_FATAL', false, 'permanent', 'invalid configuration'),
|
|
24
|
+
AlreadyClosed: spec('AlreadyClosed', 'PROVIDER_NOT_READY', false, 'permanent', 'provider already closed'),
|
|
25
|
+
Internal: spec('Internal', 'GENERAL', false, 'permanent', 'internal error'),
|
|
26
|
+
});
|
|
27
|
+
const SECRET_PATTERNS = [
|
|
28
|
+
/ph[csx]_[A-Za-z0-9]*/g, // project / secret / legacy personal API keys
|
|
29
|
+
/Bearer\s+[^\s"']+/g, // bearer tokens
|
|
30
|
+
/FW_PROJECT_API_KEY\s*[=:]\s*[^\s"']+/g,
|
|
31
|
+
];
|
|
32
|
+
/** Redact secret-shaped substrings; collapse whitespace runs; trim. */
|
|
33
|
+
export function redactSecrets(text) {
|
|
34
|
+
let out = text;
|
|
35
|
+
for (const pattern of SECRET_PATTERNS) {
|
|
36
|
+
out = out.replace(pattern, '[REDACTED]');
|
|
37
|
+
}
|
|
38
|
+
return out.replace(/\s+/g, ' ').trim();
|
|
39
|
+
}
|
|
40
|
+
export class FireweaveError extends Error {
|
|
41
|
+
kind;
|
|
42
|
+
openFeatureErrorCode;
|
|
43
|
+
retryable;
|
|
44
|
+
errorClass;
|
|
45
|
+
/** Deterministic outward-facing message from the taxonomy. */
|
|
46
|
+
safeMessage;
|
|
47
|
+
metadata;
|
|
48
|
+
constructor(kind, options = {}) {
|
|
49
|
+
const taxonomy = ERROR_TAXONOMY[kind];
|
|
50
|
+
const message = options.message !== undefined ? redactSecrets(options.message) : taxonomy.defaultMessage;
|
|
51
|
+
super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
|
|
52
|
+
this.name = 'FireweaveError';
|
|
53
|
+
this.kind = kind;
|
|
54
|
+
this.openFeatureErrorCode = options.openFeatureErrorCode ?? taxonomy.openFeatureErrorCode;
|
|
55
|
+
this.retryable = taxonomy.retryable;
|
|
56
|
+
this.errorClass = taxonomy.errorClass;
|
|
57
|
+
this.safeMessage = taxonomy.defaultMessage;
|
|
58
|
+
this.metadata = Object.freeze({ ...(options.metadata ?? {}) });
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
export function isFireweaveError(err) {
|
|
62
|
+
return err instanceof FireweaveError;
|
|
63
|
+
}
|
|
64
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/domain/errors.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../src/domain/target.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"target.js","sourceRoot":"","sources":["../../src/domain/target.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
import type { FireweaveErrorKind, OpenFeatureErrorCode } from './errors.js';
|
|
2
|
+
/** JSON-compatible value (spec/decision.schema.json `value`). */
|
|
3
|
+
export type JsonValue = string | number | boolean | null | JsonValue[] | {
|
|
4
|
+
[key: string]: JsonValue;
|
|
5
|
+
};
|
|
6
|
+
export type FlagValueType = 'boolean' | 'string' | 'number' | 'object';
|
|
7
|
+
export type DecisionReason = 'STATIC' | 'DEFAULT' | 'TARGETING_MATCH' | 'SPLIT' | 'CACHED' | 'STALE' | 'DISABLED' | 'UNKNOWN' | 'ERROR';
|
|
8
|
+
/** Canonical decision (spec/decision.schema.json). */
|
|
9
|
+
export interface Decision {
|
|
10
|
+
flagKey: string;
|
|
11
|
+
value: JsonValue;
|
|
12
|
+
reason: DecisionReason;
|
|
13
|
+
variant?: string;
|
|
14
|
+
errorCode?: OpenFeatureErrorCode;
|
|
15
|
+
errorKind?: FireweaveErrorKind;
|
|
16
|
+
errorMessage?: string;
|
|
17
|
+
/** fireweave.* flag metadata surfaced to OpenFeature flagMetadata. */
|
|
18
|
+
metadata: Record<string, string | number | boolean>;
|
|
19
|
+
}
|
|
20
|
+
/** Canonical evaluation context after validation/canonicalization. */
|
|
21
|
+
export interface CanonicalContext {
|
|
22
|
+
targetingKey?: string;
|
|
23
|
+
/** All non-reserved attributes (targetingKey excluded). */
|
|
24
|
+
attributes: Record<string, JsonValue>;
|
|
25
|
+
/**
|
|
26
|
+
* Group memberships extracted from `fireweave.groups` (canonical, ruling 13)
|
|
27
|
+
* or the plain `groups` alias, when shaped as Record<string,string>.
|
|
28
|
+
*/
|
|
29
|
+
groups?: Record<string, string>;
|
|
30
|
+
/**
|
|
31
|
+
* Group properties extracted from `fireweave.groupProperties` (canonical)
|
|
32
|
+
* or the plain `groupProperties` alias.
|
|
33
|
+
*/
|
|
34
|
+
groupProperties?: Record<string, JsonValue>;
|
|
35
|
+
}
|
|
36
|
+
export type LifecycleState = 'UNINITIALIZED' | 'INITIALIZING' | 'READY' | 'STALE' | 'ERROR' | 'FATAL' | 'SHUTDOWN';
|
|
37
|
+
export type SignalKind = 'health' | 'error' | 'metric' | 'outcome';
|
|
38
|
+
/** Canonical signal envelope (spec/signal.schema.json). */
|
|
39
|
+
export interface Signal {
|
|
40
|
+
kind: SignalKind;
|
|
41
|
+
name: string;
|
|
42
|
+
status?: string;
|
|
43
|
+
errorKind?: FireweaveErrorKind;
|
|
44
|
+
message?: string;
|
|
45
|
+
value?: number | boolean | string;
|
|
46
|
+
timestamp?: string;
|
|
47
|
+
targetingKey?: string;
|
|
48
|
+
rolloutId?: string;
|
|
49
|
+
changeId?: string;
|
|
50
|
+
stampId?: string;
|
|
51
|
+
flagKey?: string;
|
|
52
|
+
variant?: string;
|
|
53
|
+
traceId?: string;
|
|
54
|
+
role?: 'adoption' | 'guard' | 'quality' | 'custom';
|
|
55
|
+
direction?: 'up-good' | 'up-bad' | 'neutral';
|
|
56
|
+
attributes?: Record<string, string | number | boolean | null>;
|
|
57
|
+
}
|
|
58
|
+
/** Release / rollout context (spec/release-context.schema.json; ruling 15: rolloutId + stampIds required). */
|
|
59
|
+
export interface ReleaseContext {
|
|
60
|
+
stampIds: string[];
|
|
61
|
+
rolloutId: string;
|
|
62
|
+
changeId?: string;
|
|
63
|
+
surfaces?: Array<{
|
|
64
|
+
surfaceId: string;
|
|
65
|
+
kind?: 'ts-server' | 'node-server' | 'python' | 'go' | 'java' | 'web' | 'other';
|
|
66
|
+
}>;
|
|
67
|
+
metadata?: Record<string, string | number | boolean>;
|
|
68
|
+
}
|
|
69
|
+
export type ReleaseStatus = 'set' | 'in_progress' | 'completed' | 'failed';
|
|
70
|
+
export interface ReleaseState {
|
|
71
|
+
context: ReleaseContext;
|
|
72
|
+
status: ReleaseStatus;
|
|
73
|
+
reason?: string;
|
|
74
|
+
}
|
|
75
|
+
/** Exposure event (extensions fixtures shape). */
|
|
76
|
+
export interface Exposure {
|
|
77
|
+
targetingKey: string;
|
|
78
|
+
flagKey: string;
|
|
79
|
+
value: JsonValue;
|
|
80
|
+
variant?: string;
|
|
81
|
+
rolloutId?: string;
|
|
82
|
+
changeId?: string;
|
|
83
|
+
stampId?: string;
|
|
84
|
+
}
|
|
85
|
+
/** Capability matrix (spec/capabilities.schema.json). */
|
|
86
|
+
export interface Capabilities {
|
|
87
|
+
static: {
|
|
88
|
+
language: 'node';
|
|
89
|
+
sdkVersion?: string;
|
|
90
|
+
specVersion?: '0.1.0';
|
|
91
|
+
openFeature: {
|
|
92
|
+
specFloor: '0.8.0';
|
|
93
|
+
providerName: 'fireweave';
|
|
94
|
+
serverOnly?: boolean;
|
|
95
|
+
};
|
|
96
|
+
features: Record<string, boolean>;
|
|
97
|
+
};
|
|
98
|
+
runtime: {
|
|
99
|
+
backend: 'fireweave' | 'inmemory' | 'none' | 'other';
|
|
100
|
+
lifecycle: LifecycleState;
|
|
101
|
+
features?: Record<string, boolean>;
|
|
102
|
+
limits?: {
|
|
103
|
+
intSafeMaxAbs?: number;
|
|
104
|
+
shutdownTimeoutMsDefault?: number;
|
|
105
|
+
};
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/domain/types.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/domain/types.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fireweave SDK validation — pure, total functions per spec/control-points.md
|
|
3
|
+
* "Validation, before any I/O" and spec/modes.md "Initialisation validation".
|
|
4
|
+
*
|
|
5
|
+
* Every read-path validator here (`validateControlPointKey`,
|
|
6
|
+
* `validateDefaultValue`, `validateContext`, `validateTargetingKey`) returns
|
|
7
|
+
* `Validated<T>` instead of throwing. `FireweaveRuntime.evaluate` runs them,
|
|
8
|
+
* in the fixed order the spec names — key, default-vs-type, context,
|
|
9
|
+
* lifecycle — and degrades to the caller's default on the first failure; it
|
|
10
|
+
* NEVER throws (spec/control-points.md "Return discipline — never throw into
|
|
11
|
+
* a read path").
|
|
12
|
+
*
|
|
13
|
+
* `validateInitOptions` is the one named exception (spec/modes.md
|
|
14
|
+
* "Initialisation validation"): its failures are converted to a THROW by
|
|
15
|
+
* `initFireweave` (src/init.ts). The validator itself still returns
|
|
16
|
+
* `Validated<T>` — the entry point does the throwing, not this module.
|
|
17
|
+
*
|
|
18
|
+
* Collected into one module so it can move wholesale into `domain/` (plan
|
|
19
|
+
* Phase 1.4) without touching its exports or call sites again. Everything
|
|
20
|
+
* below is pure (no I/O, no ambient state) and total (every branch returns a
|
|
21
|
+
* `Validated<T>`) — `conformance/` can exercise all four read-path rules
|
|
22
|
+
* offline, with no backend.
|
|
23
|
+
*
|
|
24
|
+
* `validateInitOptions` is deliberately generic rather than importing
|
|
25
|
+
* `InitFireweaveOptions` from `init.ts`: init.ts is the "mode" entry point
|
|
26
|
+
* (Phase 1.4 assigns it to `application/`), and this module is destined for
|
|
27
|
+
* `domain/`, which must not depend on outer layers. It also does not
|
|
28
|
+
* validate "apiUrl fails the host allowlist" (spec/modes.md row 3) — that
|
|
29
|
+
* check (`assertHostAllowed`) lives in `hosts.ts`, which Phase 1.4 assigns to
|
|
30
|
+
* `infrastructure/`; it stays reachable today via `FireweaveRuntime.initialize`
|
|
31
|
+
* (runtime.ts) / `FireweaveRemoteAdapter.initialize` (adapters/remote.ts),
|
|
32
|
+
* unchanged by this module.
|
|
33
|
+
*/
|
|
34
|
+
import { FireweaveError } from './errors.js';
|
|
35
|
+
import { type ContextPolicy } from './context.js';
|
|
36
|
+
import type { CanonicalContext, JsonValue } from './types.js';
|
|
37
|
+
/** Result of a pure validator: success carries the validated value, failure the canonical error. */
|
|
38
|
+
export type Validated<T> = {
|
|
39
|
+
ok: true;
|
|
40
|
+
value: T;
|
|
41
|
+
} | {
|
|
42
|
+
ok: false;
|
|
43
|
+
error: FireweaveError;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* key — non-empty, ≤256 characters, no control characters
|
|
47
|
+
* (spec/control-points.md rule 1, the first check in the fixed order).
|
|
48
|
+
*
|
|
49
|
+
* No taxonomy kind names "malformed key" explicitly (the return-discipline
|
|
50
|
+
* table's closest row is "key unknown to the backend" → FlagNotFound): a key
|
|
51
|
+
* that can never identify a flag is treated the same as one the backend
|
|
52
|
+
* doesn't recognise, so this maps to FlagNotFound too.
|
|
53
|
+
*
|
|
54
|
+
* Controller-ruled interim mapping (Task 3 review): the 15-kind taxonomy in
|
|
55
|
+
* errors.schema.json is frozen at exactly 15 entries, `InvalidContext` is
|
|
56
|
+
* textually scoped to the evaluation *context* (not the key), and the
|
|
57
|
+
* schema already maps another non-literal case — quota-limited responses —
|
|
58
|
+
* onto `FlagNotFound` rather than adding a kind for it. `FlagNotFound` is
|
|
59
|
+
* therefore the least-wrong existing kind, not a literal fit. Other-language
|
|
60
|
+
* implementations copying node as the reference SHOULD use the same mapping
|
|
61
|
+
* rather than each independently guessing a different one.
|
|
62
|
+
*/
|
|
63
|
+
export declare function validateControlPointKey(key: string): Validated<string>;
|
|
64
|
+
export type ExpectedFlagType = 'boolean' | 'string' | 'number' | 'object';
|
|
65
|
+
/**
|
|
66
|
+
* Whether `value` matches the shape `expected` names. Shared by
|
|
67
|
+
* {@link validateDefaultValue} (the caller's default, before any I/O) and
|
|
68
|
+
* `FireweaveRuntime.evaluate`'s post-resolve check (the backend's resolved
|
|
69
|
+
* value, after I/O) — same predicate, two different inputs.
|
|
70
|
+
*/
|
|
71
|
+
export declare function matchesExpectedType(value: JsonValue, expected: ExpectedFlagType): boolean;
|
|
72
|
+
/**
|
|
73
|
+
* default vs type — e.g. `getBooleanValue` with a non-boolean default is
|
|
74
|
+
* TypeMismatch (spec/control-points.md rule 2, checked before any I/O).
|
|
75
|
+
*/
|
|
76
|
+
export declare function validateDefaultValue(expectedType: ExpectedFlagType, defaultValue: JsonValue): Validated<JsonValue>;
|
|
77
|
+
/**
|
|
78
|
+
* targetingKey: "An SDK MUST NOT invent one: a missing targeting key is
|
|
79
|
+
* InvalidContext where the evaluation needs it, never a generated anonymous
|
|
80
|
+
* id" (spec/control-points.md "Context"). `required` is call-site policy —
|
|
81
|
+
* the remote adapter always requires one for `resolve`/`registerTarget`
|
|
82
|
+
* (spec/remote-protocol.md "Two identity paths"); the generic context
|
|
83
|
+
* pipeline ({@link validateContext}) only does when
|
|
84
|
+
* `ContextPolicy.requireTargetingKey` opts in.
|
|
85
|
+
*/
|
|
86
|
+
export declare function validateTargetingKey(targetingKey: string | undefined, required: boolean): Validated<string | undefined>;
|
|
87
|
+
/**
|
|
88
|
+
* context — depth, key count, value size, reserved keys
|
|
89
|
+
* (evaluation-context.schema.json) (spec/control-points.md rule 3). Also
|
|
90
|
+
* enforces `policy.requireTargetingKey` via {@link validateTargetingKey}, and
|
|
91
|
+
* — on success — extracts `groups`/`groupProperties` the same way the former
|
|
92
|
+
* `canonicalizeContext` did.
|
|
93
|
+
*
|
|
94
|
+
* `merged` is the already-merged (global → client → invocation) raw input;
|
|
95
|
+
* merging itself (`mergeContexts`) lives in context.ts and carries no
|
|
96
|
+
* validation concerns of its own.
|
|
97
|
+
*/
|
|
98
|
+
export declare function validateContext(merged: {
|
|
99
|
+
targetingKey?: string;
|
|
100
|
+
attributes: Record<string, unknown>;
|
|
101
|
+
}, policy: ContextPolicy): Validated<CanonicalContext>;
|
|
102
|
+
/**
|
|
103
|
+
* Throwing wrapper around {@link validateContext} kept for the pre-existing
|
|
104
|
+
* public surface (`FireweaveRuntime.resolveContext`, direct callers of the
|
|
105
|
+
* package export). Read paths do not use this — they call
|
|
106
|
+
* {@link validateContext} directly so a failure degrades instead of throwing.
|
|
107
|
+
*/
|
|
108
|
+
export declare function canonicalizeContext(merged: {
|
|
109
|
+
targetingKey?: string;
|
|
110
|
+
attributes: Record<string, unknown>;
|
|
111
|
+
}, policy: ContextPolicy): CanonicalContext;
|
|
112
|
+
/**
|
|
113
|
+
* Initialisation-validation table (spec/modes.md), rows 1, 2 and 4:
|
|
114
|
+
* - `mode` absent or unrecognised
|
|
115
|
+
* - `mode: 'remote'` with `apiKey` or `apiUrl` missing/blank
|
|
116
|
+
* - `mode: 'local'` with credentials supplied (a config half-migrated from
|
|
117
|
+
* remote to local reads as neither, silently — reject it instead)
|
|
118
|
+
*
|
|
119
|
+
* Row 3 ("apiUrl fails the host allowlist") is intentionally NOT checked
|
|
120
|
+
* here — see the module doc comment.
|
|
121
|
+
*/
|
|
122
|
+
export declare function validateInitOptions<T extends {
|
|
123
|
+
readonly mode?: unknown;
|
|
124
|
+
}>(options: T): Validated<T>;
|
|
125
|
+
//# sourceMappingURL=validation.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/domain/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAkC,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE9D,oGAAoG;AACpG,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AAezF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAWtE;AAOD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE1E;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAWzF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,gBAAgB,EAC9B,YAAY,EAAE,SAAS,GACtB,SAAS,CAAC,SAAS,CAAC,CAKtB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,QAAQ,EAAE,OAAO,GAChB,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,CAU/B;AA0FD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACtE,MAAM,EAAE,aAAa,GACpB,SAAS,CAAC,gBAAgB,CAAC,CAyE7B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACtE,MAAM,EAAE,aAAa,GACpB,gBAAgB,CAIlB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,OAAO,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAsBnG"}
|