@baukit/data-contracts 0.7.2 → 0.7.3
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/dist/erasure.d.ts +1 -1
- package/dist/erasure.d.ts.map +1 -1
- package/package.json +2 -1
- package/src/contracts.ts +160 -0
- package/src/durable-draft.test.ts +1214 -0
- package/src/durable-draft.ts +502 -0
- package/src/erasure.test.ts +229 -0
- package/src/erasure.ts +162 -0
- package/src/export.test.ts +167 -0
- package/src/export.ts +164 -0
- package/src/identity.test.ts +465 -0
- package/src/identity.ts +637 -0
- package/src/import-envelope.test.ts +290 -0
- package/src/import-envelope.ts +264 -0
- package/src/import-envelope.vitest.ts +115 -0
- package/src/index.ts +7 -0
- package/src/limits-policy.test.ts +145 -0
- package/src/limits.test.ts +170 -0
- package/src/limits.ts +329 -0
- package/src/memory.test.ts +49 -0
- package/src/memory.ts +375 -0
- package/src/revisioned-drafts.fixture.test.ts +247 -0
- package/src/revisioned-writes.test.ts +684 -0
- package/src/revisioned-writes.ts +374 -0
- package/src/vitest.ts +614 -0
- package/src/web-storage.test.ts +95 -0
- package/src/web-storage.ts +88 -0
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import { describe, expect, expectTypeOf, it } from 'vitest';
|
|
2
|
+
|
|
3
|
+
import {
|
|
4
|
+
LimitError,
|
|
5
|
+
LimitExceededError,
|
|
6
|
+
LimitsPolicyError,
|
|
7
|
+
checkMeasurement,
|
|
8
|
+
checkTrimmedUnicodeScalars,
|
|
9
|
+
enforceLimit,
|
|
10
|
+
parseLimitsPolicy,
|
|
11
|
+
} from './limits.js';
|
|
12
|
+
|
|
13
|
+
const schema = {
|
|
14
|
+
version: 1,
|
|
15
|
+
sections: {
|
|
16
|
+
text: ['max_characters'],
|
|
17
|
+
transport: ['max_bytes', 'daily_budget'],
|
|
18
|
+
},
|
|
19
|
+
allowZero: ['transport.daily_budget'],
|
|
20
|
+
} as const;
|
|
21
|
+
|
|
22
|
+
const policy = {
|
|
23
|
+
$comment: 'Reviewed limits.',
|
|
24
|
+
version: 1,
|
|
25
|
+
text: { max_characters: 200 },
|
|
26
|
+
transport: { max_bytes: 1024, daily_budget: 0 },
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
describe('parseLimitsPolicy', () => {
|
|
30
|
+
it('returns the policy typed by the schema', () => {
|
|
31
|
+
const parsed = parseLimitsPolicy(policy, schema);
|
|
32
|
+
|
|
33
|
+
expect(parsed).toEqual(policy);
|
|
34
|
+
expectTypeOf(parsed.text.max_characters).toEqualTypeOf<number>();
|
|
35
|
+
expectTypeOf(parsed.transport.daily_budget).toEqualTypeOf<number>();
|
|
36
|
+
expectTypeOf(parsed).not.toHaveProperty('rows');
|
|
37
|
+
expectTypeOf(parsed.text).not.toHaveProperty('max_bytes');
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
it('rejects values that are not objects', () => {
|
|
41
|
+
for (const value of [null, [], 'limits', 1]) {
|
|
42
|
+
expectPolicyError(() => parseLimitsPolicy(value, schema), 'limits must be an object');
|
|
43
|
+
}
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
it('rejects unknown and missing top-level fields', () => {
|
|
47
|
+
expectPolicyError(
|
|
48
|
+
() => parseLimitsPolicy({ ...policy, extra: 1 }, schema),
|
|
49
|
+
'limits has unknown or missing fields',
|
|
50
|
+
);
|
|
51
|
+
const withoutComment = Object.fromEntries(
|
|
52
|
+
Object.entries(policy).filter(([key]) => key !== '$comment'),
|
|
53
|
+
);
|
|
54
|
+
expectPolicyError(
|
|
55
|
+
() => parseLimitsPolicy(withoutComment, schema),
|
|
56
|
+
'limits has unknown or missing fields',
|
|
57
|
+
);
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
it('requires a string comment and the schema version', () => {
|
|
61
|
+
expectPolicyError(
|
|
62
|
+
() => parseLimitsPolicy({ ...policy, $comment: 1 }, schema),
|
|
63
|
+
'limits.$comment must be a string',
|
|
64
|
+
);
|
|
65
|
+
expectPolicyError(
|
|
66
|
+
() => parseLimitsPolicy({ ...policy, version: 2 }, schema),
|
|
67
|
+
'Unsupported limits policy version 2',
|
|
68
|
+
);
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
it('rejects malformed sections and unknown section keys', () => {
|
|
72
|
+
expectPolicyError(
|
|
73
|
+
() => parseLimitsPolicy({ ...policy, text: null }, schema),
|
|
74
|
+
'limits.text must be an object',
|
|
75
|
+
);
|
|
76
|
+
expectPolicyError(
|
|
77
|
+
() => parseLimitsPolicy({ ...policy, text: { max_characters: 1, extra: 1 } }, schema),
|
|
78
|
+
'limits.text has unknown or missing fields',
|
|
79
|
+
);
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
it('requires positive safe integers unless the schema allows zero', () => {
|
|
83
|
+
for (const limit of [0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1, '200']) {
|
|
84
|
+
expectPolicyError(
|
|
85
|
+
() => parseLimitsPolicy({ ...policy, text: { max_characters: limit } }, schema),
|
|
86
|
+
'limits.text.max_characters must be a positive integer',
|
|
87
|
+
);
|
|
88
|
+
}
|
|
89
|
+
expectPolicyError(
|
|
90
|
+
() => parseLimitsPolicy({ ...policy, transport: { max_bytes: 1, daily_budget: -1 } }, schema),
|
|
91
|
+
'limits.transport.daily_budget must be a non-negative integer',
|
|
92
|
+
);
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
it('rejects schemas that shadow reserved fields or allow zero on unknown keys', () => {
|
|
96
|
+
expect(() => parseLimitsPolicy(policy, { version: 1, sections: { version: ['max'] } })).toThrow(
|
|
97
|
+
TypeError,
|
|
98
|
+
);
|
|
99
|
+
expect(() => parseLimitsPolicy(policy, { ...schema, allowZero: ['text.max_bytes'] })).toThrow(
|
|
100
|
+
TypeError,
|
|
101
|
+
);
|
|
102
|
+
});
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
describe('enforceLimit', () => {
|
|
106
|
+
it('returns the measurement when the value fits', () => {
|
|
107
|
+
expect(
|
|
108
|
+
enforceLimit('title', 'text_too_long', () => checkTrimmedUnicodeScalars(' ab ', 2)),
|
|
109
|
+
).toEqual({
|
|
110
|
+
measured: 2,
|
|
111
|
+
allowed: 2,
|
|
112
|
+
});
|
|
113
|
+
});
|
|
114
|
+
|
|
115
|
+
it('maps an exceeded limit to a LimitError with reason, field, and measurement', () => {
|
|
116
|
+
let caught: unknown;
|
|
117
|
+
try {
|
|
118
|
+
enforceLimit('title', 'text_too_long', () => checkTrimmedUnicodeScalars('abc', 2));
|
|
119
|
+
} catch (error) {
|
|
120
|
+
caught = error;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
expect(caught).toBeInstanceOf(LimitError);
|
|
124
|
+
expect(caught).not.toBeInstanceOf(LimitExceededError);
|
|
125
|
+
expect(caught).toMatchObject({
|
|
126
|
+
name: 'LimitError',
|
|
127
|
+
reason: 'text_too_long',
|
|
128
|
+
field: 'title',
|
|
129
|
+
measured: 3,
|
|
130
|
+
allowed: 2,
|
|
131
|
+
message: 'Limit exceeded for title: text_too_long',
|
|
132
|
+
});
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
it('passes other failures through', () => {
|
|
136
|
+
expect(() => enforceLimit('rows', 'too_many_rows', () => checkMeasurement(-1, 2))).toThrow(
|
|
137
|
+
RangeError,
|
|
138
|
+
);
|
|
139
|
+
});
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
function expectPolicyError(action: () => unknown, message: string): void {
|
|
143
|
+
expect(action).toThrow(LimitsPolicyError);
|
|
144
|
+
expect(action).toThrow(message);
|
|
145
|
+
}
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
import { describe, expect, it } from 'vitest';
|
|
2
|
+
|
|
3
|
+
import fixtureCorpus from '../../../../fixtures/limits/resource-budget-measurements-v1.json' with { type: 'json' };
|
|
4
|
+
|
|
5
|
+
import {
|
|
6
|
+
LimitExceededError,
|
|
7
|
+
ResourceMeasurementError,
|
|
8
|
+
byteLength,
|
|
9
|
+
checkBytes,
|
|
10
|
+
checkCollection,
|
|
11
|
+
checkCompactJsonUtf8Bytes,
|
|
12
|
+
checkMeasurement,
|
|
13
|
+
checkTrimmedUnicodeScalars,
|
|
14
|
+
collectionLength,
|
|
15
|
+
compactJsonUtf8Bytes,
|
|
16
|
+
trimmedUnicodeScalarCount,
|
|
17
|
+
} from './limits.js';
|
|
18
|
+
|
|
19
|
+
interface FixtureCorpus {
|
|
20
|
+
readonly version: number;
|
|
21
|
+
readonly text: readonly {
|
|
22
|
+
readonly name: string;
|
|
23
|
+
readonly value: string;
|
|
24
|
+
readonly trimmed_unicode_scalars: number;
|
|
25
|
+
}[];
|
|
26
|
+
readonly json: readonly {
|
|
27
|
+
readonly name: string;
|
|
28
|
+
readonly value: unknown;
|
|
29
|
+
readonly compact: string;
|
|
30
|
+
readonly utf8_bytes: number;
|
|
31
|
+
}[];
|
|
32
|
+
readonly bytes: readonly {
|
|
33
|
+
readonly name: string;
|
|
34
|
+
readonly value: readonly number[];
|
|
35
|
+
readonly bytes: number;
|
|
36
|
+
}[];
|
|
37
|
+
readonly collections: readonly {
|
|
38
|
+
readonly name: string;
|
|
39
|
+
readonly value: readonly unknown[];
|
|
40
|
+
readonly elements: number;
|
|
41
|
+
}[];
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
const fixtures = fixtureCorpus as FixtureCorpus;
|
|
45
|
+
|
|
46
|
+
describe('resource-budget measurements', () => {
|
|
47
|
+
it('counts ASCII, composed, decomposed, and joined emoji scalars', () => {
|
|
48
|
+
expect(trimmedUnicodeScalarCount(' plain ')).toBe(5);
|
|
49
|
+
expect(trimmedUnicodeScalarCount('\u00e9')).toBe(1);
|
|
50
|
+
expect(trimmedUnicodeScalarCount('e\u0301')).toBe(2);
|
|
51
|
+
expect(trimmedUnicodeScalarCount('👩👩👧👦')).toBe(7);
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
it('rejects unpaired JavaScript surrogates', () => {
|
|
55
|
+
expectMeasurementError(() => trimmedUnicodeScalarCount('\ud800'), 'invalid_unicode');
|
|
56
|
+
expectMeasurementError(() => trimmedUnicodeScalarCount('\udc00'), 'invalid_unicode');
|
|
57
|
+
expectMeasurementError(() => compactJsonUtf8Bytes({ value: '\ud800' }), 'invalid_unicode');
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
it('measures compact objects, arrays, escapes, and multibyte strings', () => {
|
|
61
|
+
for (const fixture of fixtures.json) {
|
|
62
|
+
expect(compactJsonUtf8Bytes(fixture.value), fixture.name).toBe(fixture.utf8_bytes);
|
|
63
|
+
expect(JSON.stringify(fixture.value), fixture.name).toBe(fixture.compact);
|
|
64
|
+
}
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
it('rejects non-finite and unsupported JavaScript values', () => {
|
|
68
|
+
expectMeasurementError(() => compactJsonUtf8Bytes(Number.NaN), 'non_finite_json_number');
|
|
69
|
+
expectMeasurementError(
|
|
70
|
+
() => compactJsonUtf8Bytes({ value: Number.POSITIVE_INFINITY }),
|
|
71
|
+
'non_finite_json_number',
|
|
72
|
+
);
|
|
73
|
+
expectMeasurementError(() => compactJsonUtf8Bytes(undefined), 'unsupported_json_value');
|
|
74
|
+
expectMeasurementError(() => compactJsonUtf8Bytes(1n), 'unsupported_json_value');
|
|
75
|
+
expectMeasurementError(() => compactJsonUtf8Bytes(() => 1), 'unsupported_json_value');
|
|
76
|
+
expectMeasurementError(
|
|
77
|
+
() => compactJsonUtf8Bytes({ value: undefined }),
|
|
78
|
+
'unsupported_json_value',
|
|
79
|
+
);
|
|
80
|
+
const sparse = new Array<unknown>(2);
|
|
81
|
+
sparse[1] = 1;
|
|
82
|
+
expectMeasurementError(() => compactJsonUtf8Bytes(sparse), 'unsupported_json_value');
|
|
83
|
+
expectMeasurementError(() => compactJsonUtf8Bytes(new Date(0)), 'unsupported_json_value');
|
|
84
|
+
|
|
85
|
+
const circular: { self?: unknown } = {};
|
|
86
|
+
circular.self = circular;
|
|
87
|
+
expectMeasurementError(() => compactJsonUtf8Bytes(circular), 'circular_json_value');
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
it('uses enumerable own string keys and rejects other own keys', () => {
|
|
91
|
+
const value: Record<string, unknown> = { visible: 1 };
|
|
92
|
+
Object.defineProperty(value, 'hidden', { value: 'private', enumerable: false });
|
|
93
|
+
expect(compactJsonUtf8Bytes(value)).toBe(13);
|
|
94
|
+
|
|
95
|
+
const nullPrototype = Object.assign(Object.create(null) as Record<string, unknown>, {
|
|
96
|
+
visible: 1,
|
|
97
|
+
});
|
|
98
|
+
expect(compactJsonUtf8Bytes(nullPrototype)).toBe(13);
|
|
99
|
+
|
|
100
|
+
const symbolKeyed = { visible: 1, [Symbol('hidden')]: 2 };
|
|
101
|
+
expectMeasurementError(() => compactJsonUtf8Bytes(symbolKeyed), 'unsupported_json_value');
|
|
102
|
+
|
|
103
|
+
const accessor = Object.defineProperty({}, 'value', {
|
|
104
|
+
enumerable: true,
|
|
105
|
+
get: () => 'private',
|
|
106
|
+
});
|
|
107
|
+
expectMeasurementError(() => compactJsonUtf8Bytes(accessor), 'unsupported_json_value');
|
|
108
|
+
|
|
109
|
+
const invalidKey = { ['\ud800']: 1 };
|
|
110
|
+
expectMeasurementError(() => compactJsonUtf8Bytes(invalidKey), 'invalid_unicode');
|
|
111
|
+
});
|
|
112
|
+
|
|
113
|
+
it('reports byte and collection boundaries', () => {
|
|
114
|
+
const bytes = Uint8Array.from([0, 1, 2]);
|
|
115
|
+
const collection = ['a', 'b', 'c'] as const;
|
|
116
|
+
expect(byteLength(bytes)).toBe(3);
|
|
117
|
+
expect(collectionLength(collection)).toBe(3);
|
|
118
|
+
expect(checkBytes(bytes, 3)).toEqual({ measured: 3, allowed: 3 });
|
|
119
|
+
expect(checkCollection(collection, 3)).toEqual({ measured: 3, allowed: 3 });
|
|
120
|
+
expectLimitExceeded(() => checkBytes(bytes, 2), 3, 2);
|
|
121
|
+
expectLimitExceeded(() => checkCollection(collection, 2), 3, 2);
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
it('returns measured and allowed values from every check', () => {
|
|
125
|
+
expect(checkMeasurement(2, 3)).toEqual({ measured: 2, allowed: 3 });
|
|
126
|
+
expect(checkTrimmedUnicodeScalars(' e\u0301 ', 2)).toEqual({ measured: 2, allowed: 2 });
|
|
127
|
+
expect(checkCompactJsonUtf8Bytes({ value: 'é' }, 14)).toEqual({ measured: 14, allowed: 14 });
|
|
128
|
+
expectLimitExceeded(() => checkMeasurement(4, 3), 4, 3);
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
it('matches the shared fixture corpus', () => {
|
|
132
|
+
expect(fixtures.version).toBe(1);
|
|
133
|
+
for (const fixture of fixtures.text) {
|
|
134
|
+
expect(trimmedUnicodeScalarCount(fixture.value), fixture.name).toBe(
|
|
135
|
+
fixture.trimmed_unicode_scalars,
|
|
136
|
+
);
|
|
137
|
+
}
|
|
138
|
+
for (const fixture of fixtures.bytes) {
|
|
139
|
+
expect(byteLength(Uint8Array.from(fixture.value)), fixture.name).toBe(fixture.bytes);
|
|
140
|
+
}
|
|
141
|
+
for (const fixture of fixtures.collections) {
|
|
142
|
+
expect(collectionLength(fixture.value), fixture.name).toBe(fixture.elements);
|
|
143
|
+
}
|
|
144
|
+
});
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
function expectMeasurementError(
|
|
148
|
+
operation: () => unknown,
|
|
149
|
+
code: ResourceMeasurementError['code'],
|
|
150
|
+
): void {
|
|
151
|
+
try {
|
|
152
|
+
operation();
|
|
153
|
+
} catch (error) {
|
|
154
|
+
expect(error).toBeInstanceOf(ResourceMeasurementError);
|
|
155
|
+
expect((error as ResourceMeasurementError).code).toBe(code);
|
|
156
|
+
return;
|
|
157
|
+
}
|
|
158
|
+
throw new Error(`Expected ResourceMeasurementError with code ${code}`);
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
function expectLimitExceeded(operation: () => unknown, measured: number, allowed: number): void {
|
|
162
|
+
try {
|
|
163
|
+
operation();
|
|
164
|
+
} catch (error) {
|
|
165
|
+
expect(error).toBeInstanceOf(LimitExceededError);
|
|
166
|
+
expect(error).toMatchObject({ measured, allowed });
|
|
167
|
+
return;
|
|
168
|
+
}
|
|
169
|
+
throw new Error('Expected LimitExceededError');
|
|
170
|
+
}
|
package/src/limits.ts
ADDED
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
export interface LimitMeasurement {
|
|
2
|
+
readonly measured: number;
|
|
3
|
+
readonly allowed: number;
|
|
4
|
+
}
|
|
5
|
+
|
|
6
|
+
export class LimitExceededError extends Error implements LimitMeasurement {
|
|
7
|
+
readonly measured: number;
|
|
8
|
+
readonly allowed: number;
|
|
9
|
+
|
|
10
|
+
constructor(measured: number, allowed: number) {
|
|
11
|
+
super(`Measured ${String(measured)} exceeds allowed ${String(allowed)}`);
|
|
12
|
+
this.name = 'LimitExceededError';
|
|
13
|
+
this.measured = measured;
|
|
14
|
+
this.allowed = allowed;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export type ResourceMeasurementErrorCode =
|
|
19
|
+
'invalid_unicode' | 'unsupported_json_value' | 'non_finite_json_number' | 'circular_json_value';
|
|
20
|
+
|
|
21
|
+
export class ResourceMeasurementError extends TypeError {
|
|
22
|
+
readonly code: ResourceMeasurementErrorCode;
|
|
23
|
+
|
|
24
|
+
constructor(code: ResourceMeasurementErrorCode) {
|
|
25
|
+
super(messageForMeasurementError(code));
|
|
26
|
+
this.name = 'ResourceMeasurementError';
|
|
27
|
+
this.code = code;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export function trimmedUnicodeScalarCount(value: string): number {
|
|
32
|
+
const scalars = unicodeScalars(value);
|
|
33
|
+
let first = 0;
|
|
34
|
+
while (first < scalars.length) {
|
|
35
|
+
const scalar = scalars[first];
|
|
36
|
+
if (scalar === undefined || !isUnicodeWhitespace(scalar)) break;
|
|
37
|
+
first += 1;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
let last = scalars.length;
|
|
41
|
+
while (last > first) {
|
|
42
|
+
const scalar = scalars[last - 1];
|
|
43
|
+
if (scalar === undefined || !isUnicodeWhitespace(scalar)) break;
|
|
44
|
+
last -= 1;
|
|
45
|
+
}
|
|
46
|
+
return last - first;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export function compactJsonUtf8Bytes(value: unknown): number {
|
|
50
|
+
assertJsonValue(value, new WeakSet());
|
|
51
|
+
return utf8ByteLength(JSON.stringify(value));
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export function byteLength(value: Uint8Array): number {
|
|
55
|
+
return value.byteLength;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export function collectionLength(value: readonly unknown[]): number {
|
|
59
|
+
return value.length;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export function checkMeasurement(measured: number, allowed: number): LimitMeasurement {
|
|
63
|
+
assertNonNegativeSafeInteger(measured, 'measured');
|
|
64
|
+
assertNonNegativeSafeInteger(allowed, 'allowed');
|
|
65
|
+
if (measured > allowed) throw new LimitExceededError(measured, allowed);
|
|
66
|
+
return { measured, allowed };
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export function checkTrimmedUnicodeScalars(value: string, allowed: number): LimitMeasurement {
|
|
70
|
+
return checkMeasurement(trimmedUnicodeScalarCount(value), allowed);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export function checkCompactJsonUtf8Bytes(value: unknown, allowed: number): LimitMeasurement {
|
|
74
|
+
return checkMeasurement(compactJsonUtf8Bytes(value), allowed);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export function checkBytes(value: Uint8Array, allowed: number): LimitMeasurement {
|
|
78
|
+
return checkMeasurement(byteLength(value), allowed);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export function checkCollection(value: readonly unknown[], allowed: number): LimitMeasurement {
|
|
82
|
+
return checkMeasurement(collectionLength(value), allowed);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
export interface LimitsPolicySchema {
|
|
86
|
+
readonly version: number;
|
|
87
|
+
readonly sections: Readonly<Record<string, readonly string[]>>;
|
|
88
|
+
readonly allowZero?: readonly string[];
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
export type LimitsPolicy<Schema extends LimitsPolicySchema> = {
|
|
92
|
+
readonly $comment: string;
|
|
93
|
+
readonly version: number;
|
|
94
|
+
} & {
|
|
95
|
+
readonly [Section in keyof Schema['sections']]: Readonly<
|
|
96
|
+
Record<Schema['sections'][Section][number], number>
|
|
97
|
+
>;
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
export class LimitsPolicyError extends Error {
|
|
101
|
+
constructor(message: string) {
|
|
102
|
+
super(message);
|
|
103
|
+
this.name = 'LimitsPolicyError';
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export class LimitError<Reason extends string = string> extends Error implements LimitMeasurement {
|
|
108
|
+
readonly reason: Reason;
|
|
109
|
+
readonly field: string;
|
|
110
|
+
readonly measured: number;
|
|
111
|
+
readonly allowed: number;
|
|
112
|
+
|
|
113
|
+
constructor(reason: Reason, field: string, measurement: LimitMeasurement) {
|
|
114
|
+
super(`Limit exceeded for ${field}: ${reason}`);
|
|
115
|
+
this.name = 'LimitError';
|
|
116
|
+
this.reason = reason;
|
|
117
|
+
this.field = field;
|
|
118
|
+
this.measured = measurement.measured;
|
|
119
|
+
this.allowed = measurement.allowed;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
const POLICY_ROOT = 'limits';
|
|
124
|
+
const RESERVED_POLICY_KEYS: readonly string[] = ['$comment', 'version'];
|
|
125
|
+
|
|
126
|
+
export function parseLimitsPolicy<const Schema extends LimitsPolicySchema>(
|
|
127
|
+
value: unknown,
|
|
128
|
+
schema: Schema,
|
|
129
|
+
): LimitsPolicy<Schema> {
|
|
130
|
+
assertPolicySchema(schema);
|
|
131
|
+
const policy = expectPolicyObject(value, POLICY_ROOT);
|
|
132
|
+
expectExactKeys(policy, [...RESERVED_POLICY_KEYS, ...Object.keys(schema.sections)], POLICY_ROOT);
|
|
133
|
+
if (typeof policy['$comment'] !== 'string') {
|
|
134
|
+
throw new LimitsPolicyError(`${POLICY_ROOT}.$comment must be a string`);
|
|
135
|
+
}
|
|
136
|
+
if (policy['version'] !== schema.version) {
|
|
137
|
+
throw new LimitsPolicyError(`Unsupported limits policy version ${String(policy['version'])}`);
|
|
138
|
+
}
|
|
139
|
+
const allowZero = new Set(schema.allowZero ?? []);
|
|
140
|
+
for (const [section, keys] of Object.entries(schema.sections)) {
|
|
141
|
+
checkPolicySection(policy, section, keys, allowZero);
|
|
142
|
+
}
|
|
143
|
+
return policy as LimitsPolicy<Schema>;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
export function enforceLimit(
|
|
147
|
+
field: string,
|
|
148
|
+
reason: string,
|
|
149
|
+
check: () => LimitMeasurement,
|
|
150
|
+
): LimitMeasurement {
|
|
151
|
+
try {
|
|
152
|
+
return check();
|
|
153
|
+
} catch (error) {
|
|
154
|
+
if (error instanceof LimitExceededError) throw new LimitError(reason, field, error);
|
|
155
|
+
throw error;
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
function assertPolicySchema(schema: LimitsPolicySchema): void {
|
|
160
|
+
const known = new Set<string>();
|
|
161
|
+
for (const [section, keys] of Object.entries(schema.sections)) {
|
|
162
|
+
if (RESERVED_POLICY_KEYS.includes(section)) {
|
|
163
|
+
throw new TypeError(`Limits policy section ${section} is reserved`);
|
|
164
|
+
}
|
|
165
|
+
for (const key of keys) known.add(`${section}.${key}`);
|
|
166
|
+
}
|
|
167
|
+
for (const path of schema.allowZero ?? []) {
|
|
168
|
+
if (!known.has(path)) throw new TypeError(`Limits policy allowZero names unknown ${path}`);
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
function checkPolicySection(
|
|
173
|
+
policy: Record<string, unknown>,
|
|
174
|
+
section: string,
|
|
175
|
+
keys: readonly string[],
|
|
176
|
+
allowZero: ReadonlySet<string>,
|
|
177
|
+
): void {
|
|
178
|
+
const path = `${POLICY_ROOT}.${section}`;
|
|
179
|
+
const values = expectPolicyObject(policy[section], path);
|
|
180
|
+
expectExactKeys(values, keys, path);
|
|
181
|
+
for (const key of keys) {
|
|
182
|
+
const minimum = allowZero.has(`${section}.${key}`) ? 0 : 1;
|
|
183
|
+
const limit = values[key];
|
|
184
|
+
if (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < minimum) {
|
|
185
|
+
const expected = minimum === 0 ? 'a non-negative integer' : 'a positive integer';
|
|
186
|
+
throw new LimitsPolicyError(`${path}.${key} must be ${expected}`);
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
function expectPolicyObject(value: unknown, path: string): Record<string, unknown> {
|
|
192
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
|
193
|
+
throw new LimitsPolicyError(`${path} must be an object`);
|
|
194
|
+
}
|
|
195
|
+
return value as Record<string, unknown>;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
function expectExactKeys(
|
|
199
|
+
value: Record<string, unknown>,
|
|
200
|
+
expected: readonly string[],
|
|
201
|
+
path: string,
|
|
202
|
+
): void {
|
|
203
|
+
const actual = Object.keys(value).sort();
|
|
204
|
+
const wanted = [...expected].sort();
|
|
205
|
+
if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
|
|
206
|
+
throw new LimitsPolicyError(`${path} has unknown or missing fields`);
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
function unicodeScalars(value: string): number[] {
|
|
211
|
+
const scalars: number[] = [];
|
|
212
|
+
for (let index = 0; index < value.length; index += 1) {
|
|
213
|
+
const first = value.charCodeAt(index);
|
|
214
|
+
if (isHighSurrogate(first)) {
|
|
215
|
+
const second = value.charCodeAt(index + 1);
|
|
216
|
+
if (!isLowSurrogate(second)) throw new ResourceMeasurementError('invalid_unicode');
|
|
217
|
+
scalars.push((first - 0xd800) * 0x400 + second - 0xdc00 + 0x10000);
|
|
218
|
+
index += 1;
|
|
219
|
+
continue;
|
|
220
|
+
}
|
|
221
|
+
if (isLowSurrogate(first)) throw new ResourceMeasurementError('invalid_unicode');
|
|
222
|
+
scalars.push(first);
|
|
223
|
+
}
|
|
224
|
+
return scalars;
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
function isHighSurrogate(value: number): boolean {
|
|
228
|
+
return value >= 0xd800 && value <= 0xdbff;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
function isLowSurrogate(value: number): boolean {
|
|
232
|
+
return value >= 0xdc00 && value <= 0xdfff;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
function isUnicodeWhitespace(value: number): boolean {
|
|
236
|
+
return (
|
|
237
|
+
(value >= 0x0009 && value <= 0x000d) ||
|
|
238
|
+
value === 0x0020 ||
|
|
239
|
+
value === 0x0085 ||
|
|
240
|
+
value === 0x00a0 ||
|
|
241
|
+
value === 0x1680 ||
|
|
242
|
+
(value >= 0x2000 && value <= 0x200a) ||
|
|
243
|
+
value === 0x2028 ||
|
|
244
|
+
value === 0x2029 ||
|
|
245
|
+
value === 0x202f ||
|
|
246
|
+
value === 0x205f ||
|
|
247
|
+
value === 0x3000
|
|
248
|
+
);
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
function assertJsonValue(value: unknown, ancestors: WeakSet<object>): void {
|
|
252
|
+
if (value === null || typeof value === 'boolean') return;
|
|
253
|
+
if (typeof value === 'string') {
|
|
254
|
+
unicodeScalars(value);
|
|
255
|
+
return;
|
|
256
|
+
}
|
|
257
|
+
if (typeof value === 'number') {
|
|
258
|
+
if (!Number.isFinite(value)) {
|
|
259
|
+
throw new ResourceMeasurementError('non_finite_json_number');
|
|
260
|
+
}
|
|
261
|
+
return;
|
|
262
|
+
}
|
|
263
|
+
if (typeof value !== 'object') {
|
|
264
|
+
throw new ResourceMeasurementError('unsupported_json_value');
|
|
265
|
+
}
|
|
266
|
+
if (ancestors.has(value)) throw new ResourceMeasurementError('circular_json_value');
|
|
267
|
+
|
|
268
|
+
ancestors.add(value);
|
|
269
|
+
try {
|
|
270
|
+
if (Object.getOwnPropertySymbols(value).length > 0) {
|
|
271
|
+
throw new ResourceMeasurementError('unsupported_json_value');
|
|
272
|
+
}
|
|
273
|
+
if (Array.isArray(value)) {
|
|
274
|
+
for (let index = 0; index < value.length; index += 1) {
|
|
275
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, index);
|
|
276
|
+
if (descriptor === undefined || !('value' in descriptor)) {
|
|
277
|
+
throw new ResourceMeasurementError('unsupported_json_value');
|
|
278
|
+
}
|
|
279
|
+
assertJsonValue(descriptor.value, ancestors);
|
|
280
|
+
}
|
|
281
|
+
return;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
const prototype = Object.getPrototypeOf(value) as object | null;
|
|
285
|
+
if (prototype !== Object.prototype && prototype !== null) {
|
|
286
|
+
throw new ResourceMeasurementError('unsupported_json_value');
|
|
287
|
+
}
|
|
288
|
+
for (const key of Object.keys(value)) {
|
|
289
|
+
unicodeScalars(key);
|
|
290
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, key);
|
|
291
|
+
if (descriptor === undefined || !('value' in descriptor)) {
|
|
292
|
+
throw new ResourceMeasurementError('unsupported_json_value');
|
|
293
|
+
}
|
|
294
|
+
assertJsonValue(descriptor.value, ancestors);
|
|
295
|
+
}
|
|
296
|
+
} finally {
|
|
297
|
+
ancestors.delete(value);
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
function utf8ByteLength(value: string): number {
|
|
302
|
+
let length = 0;
|
|
303
|
+
for (const scalar of unicodeScalars(value)) {
|
|
304
|
+
if (scalar <= 0x7f) length += 1;
|
|
305
|
+
else if (scalar <= 0x7ff) length += 2;
|
|
306
|
+
else if (scalar <= 0xffff) length += 3;
|
|
307
|
+
else length += 4;
|
|
308
|
+
}
|
|
309
|
+
return length;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
function assertNonNegativeSafeInteger(value: number, name: string): void {
|
|
313
|
+
if (!Number.isSafeInteger(value) || value < 0) {
|
|
314
|
+
throw new RangeError(`${name} must be a non-negative safe integer`);
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
function messageForMeasurementError(code: ResourceMeasurementErrorCode): string {
|
|
319
|
+
switch (code) {
|
|
320
|
+
case 'invalid_unicode':
|
|
321
|
+
return 'Strings must contain valid Unicode scalar values';
|
|
322
|
+
case 'unsupported_json_value':
|
|
323
|
+
return 'The value is not supported by compact JSON measurement';
|
|
324
|
+
case 'non_finite_json_number':
|
|
325
|
+
return 'Compact JSON measurement requires finite numbers';
|
|
326
|
+
case 'circular_json_value':
|
|
327
|
+
return 'Compact JSON measurement does not support circular values';
|
|
328
|
+
}
|
|
329
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { describe, expect, it } from 'vitest';
|
|
2
|
+
|
|
3
|
+
import type { JsonValue, StoredRecord } from './contracts.js';
|
|
4
|
+
import { InMemoryStore, InMemoryStorePool } from './memory.js';
|
|
5
|
+
import {
|
|
6
|
+
describeKeyValueContract,
|
|
7
|
+
describeRecordStoreContract,
|
|
8
|
+
describeSchemaMetadataContract,
|
|
9
|
+
describeTransactionContract,
|
|
10
|
+
describeTransactionalStorageContract,
|
|
11
|
+
describeScopedPersistenceContract,
|
|
12
|
+
} from './vitest.js';
|
|
13
|
+
|
|
14
|
+
interface TestRecord extends StoredRecord {
|
|
15
|
+
readonly label: string;
|
|
16
|
+
readonly payload: JsonValue;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
const makeStore = (): InMemoryStore<TestRecord> => new InMemoryStore<TestRecord>();
|
|
20
|
+
|
|
21
|
+
describeKeyValueContract(() => makeStore().keyValues);
|
|
22
|
+
describeRecordStoreContract(() => makeStore().records);
|
|
23
|
+
describeTransactionContract(makeStore);
|
|
24
|
+
describeTransactionalStorageContract(makeStore);
|
|
25
|
+
describeSchemaMetadataContract(() => makeStore().schemaMetadata);
|
|
26
|
+
describeScopedPersistenceContract(() => {
|
|
27
|
+
const pool = new InMemoryStorePool<TestRecord>();
|
|
28
|
+
return { open: (storeName: string) => Promise.resolve(pool.open(storeName)) };
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
describe('InMemoryStore schema migration hook', () => {
|
|
32
|
+
it('advances matching schema metadata', async () => {
|
|
33
|
+
const store = makeStore();
|
|
34
|
+
await store.schemaMetadata.setSchemaMeta({ name: 'notes', version: 1 });
|
|
35
|
+
await store.migrate({ name: 'notes', version: 1 }, { name: 'notes', version: 2 });
|
|
36
|
+
expect(await store.schemaMetadata.getSchemaMeta()).toEqual({ name: 'notes', version: 2 });
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
it('rejects a mismatched source or non-forward target', async () => {
|
|
40
|
+
const store = makeStore();
|
|
41
|
+
await store.schemaMetadata.setSchemaMeta({ name: 'notes', version: 1 });
|
|
42
|
+
await expect(
|
|
43
|
+
store.migrate({ name: 'notes', version: 0 }, { name: 'notes', version: 2 }),
|
|
44
|
+
).rejects.toThrow('does not match');
|
|
45
|
+
await expect(
|
|
46
|
+
store.migrate({ name: 'notes', version: 1 }, { name: 'notes', version: 1 }),
|
|
47
|
+
).rejects.toThrow('greater');
|
|
48
|
+
});
|
|
49
|
+
});
|