@virjay/playscope-cocos 0.0.0-stage → 0.2.0

package/dist/esm/core/OutboxStore.js

@@ -0,0 +1,224 @@
+import { parseState, PlayScopeInitializationError } from './PersistentState.js';
+import { utf8Bytes } from './FactEncoding.js';
+import { telemetryUuid } from './uuid.js';
+const KINDS = ['queue', 'quarantined'];
+const SEGMENT_BYTES = 32 * 1024;
+const SEGMENT_EVENTS = 32;
+function object(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
+function corrupt() { throw new PlayScopeInitializationError('state_corrupt'); }
+function checksum(value) {
+    let hash = 2166136261;
+    for (let i = 0; i < value.length; i++)
+        hash = Math.imul(hash ^ value.charCodeAt(i), 16777619);
+    return (hash >>> 0).toString(16);
+}
+/** Copy-on-write segments and a single atomic manifest commit. The journal bounds failed-write garbage. */
+export class OutboxStore {
+    constructor(storage, key, mode, encoding) {
+        this.storage = storage;
+        this.key = key;
+        this.encoding = encoding;
+        this.segments = [];
+        this.cleanupPending_ = false;
+        this.existed_ = false;
+        if (mode !== undefined && mode !== 'snapshot' && mode !== 'segmented')
+            throw new TypeError('Invalid persistence mode');
+        this.segmented = mode === 'segmented';
+        if (this.segmented)
+            this.requireDeletion();
+        this.prefix = `${key}:outbox:v2:`;
+        this.journalKey = `${key}:outbox:journal:v2`;
+    }
+    requireDeletion() {
+        if (typeof this.storage.removeString !== 'function')
+            throw new PlayScopeInitializationError('storage_capability_missing');
+    }
+    get mode() { return this.segmented ? 'segmented' : 'snapshot'; }
+    get cleanupPending() { return this.cleanupPending_; }
+    get hasStoredState() { return this.existed_; }
+    read(key) {
+        try {
+            return this.storage.getString(key);
+        }
+        catch {
+            throw new PlayScopeInitializationError('storage_unavailable');
+        }
+    }
+    decode(raw) { try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return corrupt();
+    } }
+    manifest(raw) {
+        if (raw === null)
+            return null;
+        const value = this.decode(raw);
+        if (!object(value) || value.schemaVersion !== 2)
+            return null;
+        if (!object(value.outbox))
+            return corrupt();
+        const keys = new Set();
+        for (const kind of KINDS) {
+            const refs = value.outbox[kind];
+            if (!Array.isArray(refs))
+                return corrupt();
+            for (const ref of refs) {
+                if (!object(ref) || typeof ref.key !== 'string' || !this.isSegmentKey(ref.key, kind) || keys.has(ref.key) ||
+                    !Number.isSafeInteger(ref.count) || ref.count < 1 || ref.count > SEGMENT_EVENTS ||
+                    !Number.isSafeInteger(ref.bytes) || ref.bytes < 1 || typeof ref.checksum !== 'string')
+                    return corrupt();
+                keys.add(ref.key);
+            }
+        }
+        return value;
+    }
+    isSegmentKey(key, kind) {
+        if (!key.startsWith(this.prefix))
+            return false;
+        const suffix = key.slice(this.prefix.length);
+        return new RegExp(`^${kind ?? '(queue|quarantined)'}:[0-9a-f-]{36}$`, 'i').test(suffix);
+    }
+    load(now, restoreCache) {
+        const raw = this.read(this.key), manifest = this.manifest(raw);
+        this.existed_ = raw !== null;
+        if (!manifest)
+            return parseState(raw, now, restoreCache);
+        this.requireDeletion();
+        this.segmented = true;
+        const lists = { queue: [], quarantined: [] };
+        for (const kind of KINDS)
+            for (const ref of manifest.outbox[kind]) {
+                const payload = this.read(ref.key);
+                if (payload === null || utf8Bytes(payload) !== ref.bytes || checksum(payload) !== ref.checksum)
+                    return corrupt();
+                const segment = this.decode(payload);
+                if (!object(segment) || segment.schemaVersion !== 2 || segment.kind !== kind ||
+                    !Array.isArray(segment.items) || segment.items.length !== ref.count || !segment.items.every(object))
+                    return corrupt();
+                lists[kind].push(...segment.items);
+                this.segments.push({ kind, ref, items: segment.items });
+            }
+        // Reuse the explicit v1 metadata/fact validator; no persisted fact is transformed by migration.
+        const state = parseState(JSON.stringify({ ...manifest, schemaVersion: 1, ...lists }), now, restoreCache);
+        // Bind descriptors to the validated objects returned by the legacy parser.
+        for (const kind of KINDS) {
+            let offset = 0;
+            for (const segment of this.segments.filter(segment => segment.kind === kind)) {
+                segment.items = state[kind].slice(offset, offset + segment.ref.count);
+                offset += segment.ref.count;
+            }
+        }
+        return state;
+    }
+    refs(manifest) {
+        return manifest ? KINDS.flatMap(kind => manifest.outbox[kind].map(ref => ref.key)) : [];
+    }
+    write(key, value) {
+        this.storage.setString(key, value);
+        this.storage.flush();
+        if (this.storage.getString(key) !== value)
+            throw new Error('storage_unavailable');
+    }
+    remove(key) {
+        this.storage.removeString(key);
+        this.storage.flush();
+        if (this.storage.getString(key) !== null)
+            throw new Error('storage_unavailable');
+    }
+    cleanup(keep) {
+        const raw = this.read(this.journalKey);
+        if (raw === null) {
+            this.cleanupPending_ = false;
+            return;
+        }
+        this.cleanupPending_ = true;
+        const journal = this.decode(raw);
+        if (!object(journal) || journal.schemaVersion !== 2 || !Array.isArray(journal.keys) ||
+            !journal.keys.every(key => typeof key === 'string' && this.isSegmentKey(key)))
+            return corrupt();
+        for (const key of journal.keys)
+            if (!keep.has(key))
+                this.remove(key);
+        this.remove(this.journalKey);
+        this.cleanupPending_ = false;
+    }
+    partition(kind, items) {
+        const old = this.segments.filter(segment => segment.kind === kind);
+        const byFirst = new Map(old.map(segment => [segment.items[0], segment]));
+        const segments = [], writes = new Map();
+        let index = 0;
+        const match = (at) => {
+            const segment = byFirst.get(items[at]);
+            return segment && segment.items.every((item, offset) => items[at + offset] === item) ? segment : undefined;
+        };
+        while (index < items.length) {
+            const previous = match(index);
+            // Rebuild a small tail when appending, so one extra fact does not create a new tiny segment.
+            if (previous && (previous !== old[old.length - 1] || index + previous.items.length === items.length || previous.items.length === SEGMENT_EVENTS ||
+                previous.ref.bytes >= SEGMENT_BYTES)) {
+                segments.push(previous);
+                index += previous.items.length;
+                continue;
+            }
+            const chunk = [], encoded = [];
+            let bytes = 0;
+            while (index < items.length && chunk.length < SEGMENT_EVENTS) {
+                if (chunk.length && match(index))
+                    break;
+                const fact = this.encoding.get(items[index]);
+                if (chunk.length && bytes + fact.bytes + 1 > SEGMENT_BYTES)
+                    break;
+                chunk.push(items[index++]);
+                encoded.push(fact.json);
+                bytes += fact.bytes + 1;
+            }
+            const payload = `{"schemaVersion":2,"kind":"${kind}","items":[${encoded.join(',')}]}`;
+            const ref = { key: `${this.prefix}${kind}:${telemetryUuid()}`, count: chunk.length,
+                bytes: utf8Bytes(payload), checksum: checksum(payload) };
+            writes.set(ref.key, payload);
+            segments.push({ kind, ref, items: chunk });
+        }
+        return { segments, writes };
+    }
+    save(state) {
+        if (!this.segmented) {
+            this.write(this.key, JSON.stringify(state));
+            return;
+        }
+        try {
+            // An earlier failure may have committed the root before its read-back failed.
+            // Always consult the actual root before collecting any staged or retired key.
+            const committed = this.manifest(this.read(this.key));
+            this.cleanup(new Set(this.refs(committed)));
+            const next = KINDS.map(kind => this.partition(kind, state[kind]));
+            const segments = next.flatMap(part => part.segments);
+            const writes = new Map(next.flatMap(part => [...part.writes]));
+            const retained = new Set(segments.map(segment => segment.ref.key));
+            const garbage = this.refs(committed).filter(key => !retained.has(key));
+            if (writes.size || garbage.length) {
+                // Persist intent before the first new key, retaining every old referenced key until commit.
+                this.write(this.journalKey, JSON.stringify({ schemaVersion: 2, keys: [...writes.keys(), ...garbage] }));
+                this.cleanupPending_ = true;
+                for (const [key, value] of writes)
+                    this.write(key, value);
+            }
+            const { queue: _queue, quarantined: _quarantined, ...metadata } = state;
+            const root = JSON.stringify({ ...metadata, schemaVersion: 2, outbox: {
+                    queue: next[0].segments.map(segment => segment.ref), quarantined: next[1].segments.map(segment => segment.ref)
+                } });
+            this.write(this.key, root);
+            this.segments = segments;
+            // GC is not part of fact durability. A failed cleanup remains journaled and must finish before another write.
+            try {
+                this.cleanup(retained);
+            }
+            catch { /* Retry cleanup before the next persistence operation. */ }
+        }
+        catch (error) {
+            // Reconciliation after an uncertain commit must not reuse references that GC might have retired.
+            this.segments = [];
+            throw error;
+        }
+    }
+}

package/dist/esm/core/PersistentState.js

@@ -0,0 +1,85 @@
+import { telemetryUuid } from './uuid.js';
+/** Construction fails without overwriting stored data. Retry by constructing a new client. */
+export class PlayScopeInitializationError extends Error {
+    constructor(code) {
+        super(`PlayScope initialization failed: ${code}`);
+        this.code = code;
+        this.name = 'PlayScopeInitializationError';
+        this.retryable = code === 'storage_unavailable';
+    }
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function isEventFact(value) {
+    return object(value) && typeof value.eventId === 'string' && value.eventId.length > 0 && typeof value.name === 'string';
+}
+function integer(value) { return Number.isSafeInteger(value) && value >= 0; }
+function isClientScope(value) {
+    return object(value) && typeof value.baseUrl === 'string' && !!value.baseUrl.replace(/\/+$/, '') &&
+        typeof value.projectId === 'string' && !!value.projectId && ['production', 'test'].includes(value.environment);
+}
+export function loadState(storage, key, now, restoreCache) {
+    let raw;
+    try {
+        raw = storage.getString(key);
+    }
+    catch {
+        throw new PlayScopeInitializationError('storage_unavailable');
+    }
+    return parseState(raw, now, restoreCache);
+}
+export function parseState(raw, now, restoreCache) {
+    // Only an explicit missing key is a new installation. Empty/invalid data is preserved.
+    let state;
+    if (raw === null) {
+        state = { schemaVersion: 1, installId: telemetryUuid(), firstOpenedAt: new Date(now()).toISOString(),
+            firstOpenTracked: false, sequence: 0, token: null, cache: null, queue: [], quarantined: [], rejected: [], droppedEvents: 0 };
+    }
+    else {
+        let saved;
+        try {
+            saved = JSON.parse(raw);
+        }
+        catch {
+            throw new PlayScopeInitializationError('state_corrupt');
+        }
+        if (!object(saved))
+            throw new PlayScopeInitializationError('state_corrupt');
+        if (saved.schemaVersion !== undefined && saved.schemaVersion !== 1)
+            throw new PlayScopeInitializationError('state_version_unsupported');
+        if (typeof saved.installId !== 'string' || !/^[0-9a-f-]{36}$/i.test(saved.installId) ||
+            typeof saved.firstOpenedAt !== 'string' || !Number.isFinite(Date.parse(saved.firstOpenedAt)) ||
+            typeof saved.firstOpenTracked !== 'boolean' || !integer(saved.sequence) ||
+            !Array.isArray(saved.queue) || !saved.queue.every(isEventFact))
+            throw new PlayScopeInitializationError('state_corrupt');
+        const quarantine = saved.quarantined ?? [];
+        if (!Array.isArray(quarantine) || !quarantine.every(value => object(value) && isEventFact(value.event) &&
+            (value.reason === 'event_too_large' || value.reason === 'http_413') && typeof value.quarantinedAt === 'string'))
+            throw new PlayScopeInitializationError('state_corrupt');
+        const token = saved.token;
+        const scope = saved.scope;
+        if (scope !== undefined && !isClientScope(scope))
+            throw new PlayScopeInitializationError('state_corrupt');
+        // Versionless state is the original SDK/BlockDrop shape. Migration adds metadata;
+        // queued facts, IDs, sequence, first-open marker and identity are never recreated.
+        state = { schemaVersion: 1, installId: saved.installId, firstOpenedAt: saved.firstOpenedAt,
+            firstOpenTracked: saved.firstOpenTracked, sequence: saved.sequence, queue: saved.queue, quarantined: quarantine,
+            token: object(token) && typeof token.accessToken === 'string' && typeof token.expiresAt === 'string' &&
+                Number.isFinite(Date.parse(token.expiresAt)) ? { accessToken: token.accessToken, expiresAt: token.expiresAt } : null,
+            cache: saved.cache ?? null, droppedEvents: integer(saved.droppedEvents) ? saved.droppedEvents : 0,
+            rejected: Array.isArray(saved.rejected) ? saved.rejected.slice(-50) : [],
+            ...(Array.isArray(saved.deduplicationKeys)
+                ? { deduplicationKeys: saved.deduplicationKeys.filter((key) => typeof key === 'string').slice(-2000) } : {}),
+            ...(scope ? { scope: { baseUrl: scope.baseUrl, projectId: scope.projectId, environment: scope.environment } } : {}) };
+    }
+    if (restoreCache) {
+        try {
+            state.cache = restoreCache(state.cache);
+        }
+        catch {
+            throw new PlayScopeInitializationError('cache_restore_failed');
+        }
+    }
+    return state;
+}