@mpgd/game-services 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export * from './client';
 export * from './contract';
 export * from './notification-delivery';
 export * from './progress-link';
+export * from './runtime.js';
 export * from './server';
 export * from './types';

package/dist/index.js

@@ -2,5 +2,6 @@ export * from './client';
 export * from './contract';
 export * from './notification-delivery';
 export * from './progress-link';
+export * from './runtime.js';
 export * from './server';
 export * from './types';

package/dist/runtime.d.ts

@@ -0,0 +1,31 @@
+import type { AnalyticsSink } from '@mpgd/analytics';
+import type { PlatformGateway, PlatformTarget } from '@mpgd/platform';
+import { type GameServicesBackendApi, type GameServicesClient } from './client.js';
+import type { GameServicesLedgerTarget } from './types.js';
+export type GameServicesAuthorityMode = 'production' | 'non-production';
+export type GameServicesRuntimeMode = 'disabled' | 'local' | 'http' | 'orpc';
+export type GameServicesDisabledReason = 'unsupported_target' | 'missing_authoritative_backend' | 'invalid_authoritative_backend' | 'local_backend_not_allowed' | 'local_backend_unavailable';
+export interface GameServicesRuntime {
+  readonly mode: GameServicesRuntimeMode;
+  readonly reason?: GameServicesDisabledReason;
+  readonly baseUrl?: string;
+  readonly target?: GameServicesLedgerTarget;
+  readonly client?: GameServicesClient;
+}
+export interface CreateGameServicesRuntimeInput {
+  readonly gateway: PlatformGateway;
+  readonly playerId: string;
+  readonly authorityMode: GameServicesAuthorityMode;
+  readonly target?: PlatformTarget | string;
+  readonly baseUrl?: string;
+  readonly transport?: 'http' | 'orpc';
+  readonly allowLocalBackend?: boolean;
+  readonly localBackend?: GameServicesBackendApi;
+  readonly analytics?: AnalyticsSink;
+  readonly analyticsSessionId?: string;
+  readonly now?: () => string;
+}
+export declare function createGameServicesRuntime(input: CreateGameServicesRuntimeInput): GameServicesRuntime;
+export declare function resolveGameServicesLedgerTarget(target: PlatformTarget | string): GameServicesLedgerTarget | null;
+export declare function resolveGameServicesAuthorityMode(profile: string): GameServicesAuthorityMode;
+export declare function resolveGameServicesTransport(transport: string | undefined): 'http' | 'orpc';

package/dist/runtime.js

@@ -0,0 +1,198 @@
+import { createGameServicesClient, createGameServicesFetchBackendTransport, createGameServicesHttpBackendApi, createGameServicesOrpcBackendApi, createGameServicesOrpcClient, } from './client.js';
+export function createGameServicesRuntime(input) {
+    assertAuthorityMode(input.authorityMode);
+    assertTransport(input.transport);
+    const target = resolveGameServicesLedgerTarget(input.target ?? input.gateway.target);
+    if (target === null) {
+        return disabledRuntime('unsupported_target');
+    }
+    const baseUrl = normalizeBaseUrl(input.baseUrl);
+    let backend;
+    let mode;
+    if (baseUrl !== undefined) {
+        const url = parseAbsoluteUrl(baseUrl);
+        if (input.authorityMode === 'production' && !isPublicHttpsUrl(url)) {
+            return disabledRuntime('invalid_authoritative_backend', target);
+        }
+        if (url === undefined) {
+            throw new Error('Game Services baseUrl must be a valid absolute URL.');
+        }
+        mode = input.transport === 'orpc' ? 'orpc' : 'http';
+        backend = mode === 'orpc'
+            ? createGameServicesOrpcBackendApi(createGameServicesOrpcClient({ url: baseUrl }))
+            : createGameServicesHttpBackendApi({
+                transport: createGameServicesFetchBackendTransport({ baseUrl }),
+            });
+    }
+    else {
+        if (input.authorityMode === 'production') {
+            return disabledRuntime('missing_authoritative_backend', target);
+        }
+        if (input.allowLocalBackend !== true) {
+            return disabledRuntime('local_backend_not_allowed', target);
+        }
+        if (input.localBackend === undefined) {
+            return disabledRuntime('local_backend_unavailable', target);
+        }
+        mode = 'local';
+        backend = input.localBackend;
+    }
+    return {
+        mode,
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        target,
+        client: createGameServicesClient({
+            gateway: input.gateway,
+            backend,
+            playerId: input.playerId,
+            target,
+            ...(input.analytics === undefined ? {} : { analytics: input.analytics }),
+            ...(input.analyticsSessionId === undefined
+                ? {}
+                : { analyticsSessionId: input.analyticsSessionId }),
+            ...(input.now === undefined ? {} : { now: input.now }),
+        }),
+    };
+}
+export function resolveGameServicesLedgerTarget(target) {
+    if (target === 'browser'
+        || target === 'android'
+        || target === 'ios'
+        || target === 'ait'
+        || target === 'reddit') {
+        return target;
+    }
+    return null;
+}
+export function resolveGameServicesAuthorityMode(profile) {
+    if (profile.length === 0 || profile.trim() !== profile) {
+        throw new Error('Game Services profile must be non-empty without surrounding whitespace.');
+    }
+    return profile === 'production' ? 'production' : 'non-production';
+}
+export function resolveGameServicesTransport(transport) {
+    if (transport === undefined || transport.length === 0 || transport === 'http') {
+        return 'http';
+    }
+    if (transport === 'orpc') {
+        return 'orpc';
+    }
+    throw new Error('Game Services transport must be http or orpc.');
+}
+function disabledRuntime(reason, target) {
+    return {
+        mode: 'disabled',
+        reason,
+        ...(target === undefined ? {} : { target }),
+    };
+}
+function normalizeBaseUrl(baseUrl) {
+    const normalized = baseUrl?.trim();
+    return normalized === undefined || normalized.length === 0 ? undefined : normalized;
+}
+function isPublicHttpsUrl(url) {
+    return url !== undefined
+        && url.protocol === 'https:'
+        && url.username.length === 0
+        && url.password.length === 0
+        && !isNonPublicHostname(url.hostname);
+}
+function parseAbsoluteUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isNonPublicHostname(hostname) {
+    const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/u, '');
+    if (normalized === 'localhost'
+        || normalized.endsWith('.localhost')
+        || normalized.endsWith('.local')) {
+        return true;
+    }
+    if (/^(?:\d{1,3}\.){3}\d{1,3}$/u.test(normalized)) {
+        return isNonPublicIpv4(normalized);
+    }
+    return normalized.includes(':') && isNonPublicIpv6(normalized);
+}
+function isNonPublicIpv4(address) {
+    const [first = 0, second = 0, third = 0] = address.split('.').map(Number);
+    return first === 0
+        || first === 10
+        || first === 127
+        || (first === 100 && second >= 64 && second <= 127)
+        || (first === 169 && second === 254)
+        || (first === 172 && second >= 16 && second <= 31)
+        || (first === 192 && second === 0 && third === 0)
+        || (first === 192 && second === 0 && third === 2)
+        || (first === 192 && second === 168)
+        || (first === 198 && (second === 18 || second === 19))
+        || (first === 198 && second === 51 && third === 100)
+        || (first === 203 && second === 0 && third === 113)
+        || first >= 224;
+}
+function isNonPublicIpv6(address) {
+    const words = expandIpv6(address);
+    if (words === undefined) {
+        return true;
+    }
+    if (words.slice(0, 7).every((word) => word === 0)) {
+        return true;
+    }
+    if (words.slice(0, 5).every((word) => word === 0) && words[5] === 0xffff) {
+        return isNonPublicIpv4(wordsToIpv4(words));
+    }
+    if (words.slice(0, 6).every((word) => word === 0)) {
+        return isNonPublicIpv4(wordsToIpv4(words));
+    }
+    const first = words[0] ?? 0;
+    return (first & 0xfe00) === 0xfc00
+        || (first & 0xffc0) === 0xfe80
+        || (first & 0xff00) === 0xff00
+        || (first === 0x2001 && words[1] === 0x0db8);
+}
+function wordsToIpv4(words) {
+    return `${(words[6] ?? 0) >> 8}.${(words[6] ?? 0) & 0xff}.`
+        + `${(words[7] ?? 0) >> 8}.${(words[7] ?? 0) & 0xff}`;
+}
+function expandIpv6(address) {
+    const sections = address.split('::');
+    if (sections.length > 2) {
+        return undefined;
+    }
+    const head = ipv6Words(sections[0] ?? '');
+    const tail = ipv6Words(sections[1] ?? '');
+    if (head === undefined || tail === undefined) {
+        return undefined;
+    }
+    const omitted = 8 - head.length - tail.length;
+    if ((sections.length === 1 && omitted !== 0) || (sections.length === 2 && omitted < 1)) {
+        return undefined;
+    }
+    return [...head, ...Array.from({ length: omitted }, () => 0), ...tail];
+}
+function ipv6Words(section) {
+    if (section.length === 0) {
+        return [];
+    }
+    const words = [];
+    for (const segment of section.split(':')) {
+        if (!/^[0-9a-f]{1,4}$/u.test(segment)) {
+            return undefined;
+        }
+        words.push(Number.parseInt(segment, 16));
+    }
+    return words;
+}
+function assertAuthorityMode(authorityMode) {
+    if (authorityMode !== 'production' && authorityMode !== 'non-production') {
+        throw new Error('authorityMode must be production or non-production.');
+    }
+}
+function assertTransport(transport) {
+    if (transport !== undefined && transport !== 'http' && transport !== 'orpc') {
+        throw new Error('Game Services transport must be http or orpc.');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -45,6 +45,10 @@
       "types": "./dist/progress-link.d.ts",
       "default": "./dist/progress-link.js"
     },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
     "./server": {
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
@@ -61,9 +65,9 @@
     "@orpc/client": "2.0.0-beta.14",
     "@orpc/contract": "2.0.0-beta.14",
     "@orpc/server": "2.0.0-beta.14",
-    "@mpgd/analytics": "0.3.3",
-    "@mpgd/catalog": "0.3.3",
-    "@mpgd/platform": "0.4.0"
+    "@mpgd/catalog": "0.3.4",
+    "@mpgd/analytics": "0.3.4",
+    "@mpgd/platform": "0.5.0"
   },
   "devDependencies": {
     "ttsc": "0.16.9",
@@ -79,6 +83,6 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts"
+    "test": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/runtime.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts"
   }
 }