telepact 1.0.0-alpha.338 → 1.0.0-alpha.339

package/dist/inc/internal.telepact.json

@@ -1,16 +1,17 @@
 [
     {
         "///": "Ping the server.",
+        "$internal": true,
         "fn.ping_": {},
         "->": [
             {
                 "Ok_": {}
             }
-        ],
-        "_errors": "^errors\\.Validation_$"
+        ]
     },
     {
         "///": "Get the telepact `schema` of this server.\n\nSet `includeInternal` to `true` to include Telepact internal definitions.\nSet `includeExamples` to `true` to add deterministic example payloads to\neach schema entry.\n",
+        "$internal": true,
         "fn.api_": {
             "includeInternal!": "boolean",
             "includeExamples!": "boolean"
@@ -25,8 +26,7 @@
                     ]
                 }
             }
-        ],
-        "_errors": "^errors\\.Validation_$"
+        ]
     },
     {
         "///": "`_ext.Select_` is the selection object used by the `@select_` header. Use\n`->` to narrow fields on the active result union, `struct.*` keys to narrow\nstruct fields, and `union.*` keys to narrow fields for specific union tags.\n\nSee https://raw.githubusercontent.com/Telepact/telepact/main/doc/02-design-apis/04-select-extension.md\nfor full `_ext.Select_` rules and end-to-end examples.\n",

package/dist/inc/mock-internal.telepact.json

@@ -52,6 +52,7 @@
     },
     {
         "///": "Create a mock stub from an `_ext.Stub_`.\n\nBy default the stub matcher is partial, so extra fields on the actual\nrequest argument are allowed. Set `strictMatch!` to `true` to require exact\nargument equality instead.\n\nSet `count!` to limit how many matching calls consume this stub before it\nstops matching.\n",
+        "$internal": true,
         "fn.createStub_": {
             "stub": "_ext.Stub_",
             "strictMatch!": "boolean",
@@ -61,11 +62,11 @@
             {
                 "Ok_": {}
             }
-        ],
-        "_errors": "^errors\\.Validation_$"
+        ]
     },
     {
         "///": "Verify that the mock received a call matching the given `_ext.Call_`.\n\nBy default verification is partial and succeeds if at least one recorded\ncall contains the given argument as a JSON sub-structure. Set\n`strictMatch!` to `true` to require exact argument equality.\n\nSet `count!` to require `Exact`, `AtLeast`, or `AtMost` matching call\ncounts. Matching calls are marked as verified, which affects\n`fn.verifyNoMoreInteractions_`.\n",
+        "$internal": true,
         "fn.verify_": {
             "call": "_ext.Call_",
             "strictMatch!": "boolean",
@@ -80,11 +81,11 @@
                     "reason": "union.VerificationFailure_"
                 }
             }
-        ],
-        "_errors": "^errors\\.Validation_$"
+        ]
     },
     {
         "///": "Verify that no interactions have occurred with this mock or that all\ninteractions have been verified.\n",
+        "$internal": true,
         "fn.verifyNoMoreInteractions_": {},
         "->": [
             {
@@ -97,31 +98,31 @@
                     ]
                 }
             }
-        ],
-        "_errors": "^errors\\.Validation_$"
+        ]
     },
     {
         "///": "Clear all stub conditions.",
+        "$internal": true,
         "fn.clearStubs_": {},
         "->": [
             {
                 "Ok_": {}
             }
-        ],
-        "_errors": "^errors\\.Validation_$"
+        ]
     },
     {
         "///": "Clear all call data.",
+        "$internal": true,
         "fn.clearCalls_": {},
         "->": [
             {
                 "Ok_": {}
             }
-        ],
-        "_errors": "^errors\\.Validation_$"
+        ]
     },
     {
         "///": "Set the seed of the random generator.",
+        "$internal": true,
         "fn.setRandomSeed_": {
             "seed": "integer"
         },
@@ -129,8 +130,7 @@
             {
                 "Ok_": {}
             }
-        ],
-        "_errors": "^errors\\.Validation_$"
+        ]
     },
     {
         "errors.Mock_": [

package/dist/index.cjs.js

@@ -1100,34 +1100,13 @@ class ClientOptions {
 }
 
 class FunctionRouter {
-    authenticatedFunctionRoutes;
-    unauthenticatedFunctionRoutes;
-    constructor() {
-        this.authenticatedFunctionRoutes = {};
-        this.unauthenticatedFunctionRoutes = {};
-    }
-    registerAuthenticatedRoutes(functionRoutes) {
-        for (const [functionName, functionRoute] of Object.entries(functionRoutes)) {
-            this.authenticatedFunctionRoutes[functionName] = functionRoute;
-            delete this.unauthenticatedFunctionRoutes[functionName];
-        }
-    }
-    registerUnauthenticatedRoutes(functionRoutes) {
-        for (const [functionName, functionRoute] of Object.entries(functionRoutes)) {
-            this.unauthenticatedFunctionRoutes[functionName] = functionRoute;
-            delete this.authenticatedFunctionRoutes[functionName];
-        }
-    }
-    hasAuthenticatedRoutes() {
-        return Object.keys(this.authenticatedFunctionRoutes).length > 0;
-    }
-    requiresAuthentication(functionName) {
-        return functionName in this.authenticatedFunctionRoutes;
+    functionRoutes;
+    constructor(functionRoutes = {}) {
+        this.functionRoutes = { ...functionRoutes };
     }
     async route(requestMessage) {
         const functionName = requestMessage.getBodyTarget();
-        const functionRoute = this.authenticatedFunctionRoutes[functionName]
-            ?? this.unauthenticatedFunctionRoutes[functionName];
+        const functionRoute = this.functionRoutes[functionName];
         if (functionRoute === undefined) {
             throw new Error(`Unknown function: ${functionName}`);
         }
@@ -1874,6 +1853,20 @@ function buildUnknownErrorMessage(error, headers = {}) {
     return new Message(headers, { ErrorUnknown_: { caseId: error.caseId } });
 }
 
+function requiresAuthentication(telepactSchema, functionName) {
+    const functionDefinition = telepactSchema.full.find((definition) => typeof definition === 'object'
+        && definition !== null
+        && !Array.isArray(definition)
+        && functionName in definition);
+    if (functionName.endsWith('_') || functionDefinition?.['$internal'] === true) {
+        return false;
+    }
+    if (!('union.Auth_' in telepactSchema.parsed)) {
+        return false;
+    }
+    return functionDefinition?.['$authenticated'] !== false;
+}
+
 const UNAUTHENTICATED_MESSAGE = 'Valid authentication is required.';
 async function handleMessage(requestMessage, updateHeaders, telepactSchema, middleware, functionRouter, onError, onAuth) {
     const responseHeaders = {};
@@ -1897,7 +1890,8 @@ async function handleMessage(requestMessage, updateHeaders, telepactSchema, midd
     const functionName = requestTarget;
     const callType = parsedTelepactSchema[requestTarget];
     const resultUnionType = parsedTelepactSchema[`${requestTarget}.->`];
-    const requiresAuthentication = unknownTarget === null && functionRouter.requiresAuthentication(functionName);
+    const functionRequiresAuthentication = unknownTarget === null
+        && requiresAuthentication(telepactSchema, functionName);
     const callId = requestHeaders['@id_'];
     if (callId !== undefined) {
         responseHeaders['@id_'] = callId;
@@ -1914,10 +1908,10 @@ async function handleMessage(requestMessage, updateHeaders, telepactSchema, midd
     if (requestHeaderValidationFailures.length > 0) {
         return getInvalidErrorMessage('ErrorInvalidRequestHeaders_', requestHeaderValidationFailures, resultUnionType, responseHeaders);
     }
-    if (requiresAuthentication && !('@auth_' in requestHeaders)) {
+    if (functionRequiresAuthentication && !('@auth_' in requestHeaders)) {
         return buildUnauthenticatedErrorMessage(resultUnionType, responseHeaders);
     }
-    if (requiresAuthentication) {
+    if (functionRequiresAuthentication) {
         try {
             const authHeaders = (await onAuth(requestHeaders)) ?? {};
             Object.assign(requestHeaders, authHeaders);
@@ -2378,7 +2372,7 @@ function getDefaultFnScope(parsedTypes) {
 }
 function getSchemaKey(definition) {
     for (const key of Object.keys(definition)) {
-        if (key !== '///' && key !== '->' && key !== '_errors') {
+        if (key !== '///' && key !== '->' && key !== '_errors' && !key.startsWith('$')) {
             return key;
         }
     }
@@ -2412,11 +2406,13 @@ class Server {
     telepactSchema;
     serializer;
     constructor(telepactSchema, functionRouter, options) {
-        const normalizedFunctionRouter = functionRouter instanceof FunctionRouter ? functionRouter : new FunctionRouter();
-        if (!(functionRouter instanceof FunctionRouter)) {
-            normalizedFunctionRouter.registerUnauthenticatedRoutes(functionRouter);
-        }
-        normalizedFunctionRouter.registerUnauthenticatedRoutes(createInternalFunctionRoutes(telepactSchema));
+        const normalizedFunctionRouter = functionRouter instanceof FunctionRouter
+            ? functionRouter
+            : new FunctionRouter(functionRouter);
+        normalizedFunctionRouter.functionRoutes = {
+            ...normalizedFunctionRouter.functionRoutes,
+            ...createInternalFunctionRoutes(telepactSchema),
+        };
         this.functionRouter = normalizedFunctionRouter;
         this.middleware = options.middleware;
         this.onError = options.onError;
@@ -2428,8 +2424,8 @@ class Server {
         const binaryEncoder = new ServerBinaryEncoder(binaryEncoding);
         const base64Encoder = new ServerBase64Encoder();
         this.serializer = new Serializer(options.serialization, binaryEncoder, base64Encoder);
-        if (!('union.Auth_' in this.telepactSchema.parsed) && this.functionRouter.hasAuthenticatedRoutes()) {
-            throw new Error('Authenticated routes require `union.Auth_` in your schema.');
+        if (!('union.Auth_' in this.telepactSchema.parsed) && options.authRequired) {
+            throw new Error('Unauthenticated server. Either define a `union.Auth_` in your schema or set `options.authRequired` to `false`.');
         }
     }
     async process(requestMessageBytes, updateHeaders) {
@@ -2442,6 +2438,7 @@ class ServerOptions {
     onResponse;
     onAuth;
     middleware;
+    authRequired;
     serialization;
     constructor() {
         this.onError = (_error) => { };
@@ -2449,6 +2446,7 @@ class ServerOptions {
         this.onResponse = (m) => { };
         this.onAuth = (headers) => ({});
         this.middleware = async (requestMessage, functionRouter) => await functionRouter.route(requestMessage);
+        this.authRequired = true;
         this.serialization = new DefaultSerialization();
     }
 }
@@ -2496,6 +2494,7 @@ function isSubMap(part, whole) {
 var internalTelepact = [
 	{
 		"///": "Ping the server.",
+		$internal: true,
 		"fn.ping_": {
 		},
 		"->": [
@@ -2503,11 +2502,11 @@ var internalTelepact = [
 				Ok_: {
 				}
 			}
-		],
-		_errors: "^errors\\.Validation_$"
+		]
 	},
 	{
 		"///": "Get the telepact `schema` of this server.\n\nSet `includeInternal` to `true` to include Telepact internal definitions.\nSet `includeExamples` to `true` to add deterministic example payloads to\neach schema entry.\n",
+		$internal: true,
 		"fn.api_": {
 			"includeInternal!": "boolean",
 			"includeExamples!": "boolean"
@@ -2522,8 +2521,7 @@ var internalTelepact = [
 					]
 				}
 			}
-		],
-		_errors: "^errors\\.Validation_$"
+		]
 	},
 	{
 		"///": "`_ext.Select_` is the selection object used by the `@select_` header. Use\n`->` to narrow fields on the active result union, `struct.*` keys to narrow\nstruct fields, and `union.*` keys to narrow fields for specific union tags.\n\nSee https://raw.githubusercontent.com/Telepact/telepact/main/doc/02-design-apis/04-select-extension.md\nfor full `_ext.Select_` rules and end-to-end examples.\n",
@@ -10590,15 +10588,18 @@ function parseFunctionResultType(path, functionDefinitionAsParsedJson, schemaKey
 function parseFunctionErrorsRegex(path, functionDefinitionAsParsedJson, schemaKey, ctx) {
     const parseFailures = [];
     const errorsRegexKey = '_errors';
+    const isInternal = schemaKey.endsWith('_') || functionDefinitionAsParsedJson['$internal'] === true;
     const regexPath = [...path, errorsRegexKey];
     let errorsRegex = null;
-    if (errorsRegexKey in functionDefinitionAsParsedJson && !schemaKey.endsWith('_')) {
+    if (errorsRegexKey in functionDefinitionAsParsedJson && !isInternal) {
         parseFailures.push(new SchemaParseFailure(ctx.documentName, regexPath, 'ObjectKeyDisallowed', {}));
     }
     else {
         const errorsRegexInit = errorsRegexKey in functionDefinitionAsParsedJson
             ? functionDefinitionAsParsedJson[errorsRegexKey]
-            : '^errors\\..*$';
+            : isInternal
+                ? '^errors\\.Validation_$'
+                : '^errors\\..*$';
         if (typeof errorsRegexInit !== 'string') {
             const thisParseFailures = getTypeUnexpectedParseFailure(ctx.documentName, regexPath, errorsRegexInit, 'String');
             parseFailures.push(...thisParseFailures);
@@ -10615,7 +10616,7 @@ function parseFunctionErrorsRegex(path, functionDefinitionAsParsedJson, schemaKe
 
 function parseStructType(path, structDefinitionAsPseudoJson, schemaKey, ignoreKeys, ctx) {
     const parseFailures = [];
-    const otherKeys = new Set(Object.keys(structDefinitionAsPseudoJson));
+    const otherKeys = new Set(Object.keys(structDefinitionAsPseudoJson).filter((key) => !key.startsWith('$')));
     otherKeys.delete(schemaKey);
     otherKeys.delete('///');
     otherKeys.delete('_ignoreIfDuplicate');
@@ -11939,9 +11940,9 @@ class MockServer {
         this.invocations = [];
         const serverOptions = new ServerOptions();
         serverOptions.onError = options.onError;
+        serverOptions.authRequired = false;
         const telepactSchema = new TelepactSchema(mockTelepactSchema.original, mockTelepactSchema.full, mockTelepactSchema.parsed, mockTelepactSchema.parsedRequestHeaders, mockTelepactSchema.parsedResponseHeaders);
-        const functionRouter = new FunctionRouter();
-        functionRouter.registerUnauthenticatedRoutes(this.createFunctionRoutes(telepactSchema));
+        const functionRouter = new FunctionRouter(this.createFunctionRoutes(telepactSchema));
         this.server = new Server(telepactSchema, functionRouter, serverOptions);
     }
     random;
@@ -12049,6 +12050,7 @@ var mockInternalTelepact = [
 	},
 	{
 		"///": "Create a mock stub from an `_ext.Stub_`.\n\nBy default the stub matcher is partial, so extra fields on the actual\nrequest argument are allowed. Set `strictMatch!` to `true` to require exact\nargument equality instead.\n\nSet `count!` to limit how many matching calls consume this stub before it\nstops matching.\n",
+		$internal: true,
 		"fn.createStub_": {
 			stub: "_ext.Stub_",
 			"strictMatch!": "boolean",
@@ -12059,11 +12061,11 @@ var mockInternalTelepact = [
 				Ok_: {
 				}
 			}
-		],
-		_errors: "^errors\\.Validation_$"
+		]
 	},
 	{
 		"///": "Verify that the mock received a call matching the given `_ext.Call_`.\n\nBy default verification is partial and succeeds if at least one recorded\ncall contains the given argument as a JSON sub-structure. Set\n`strictMatch!` to `true` to require exact argument equality.\n\nSet `count!` to require `Exact`, `AtLeast`, or `AtMost` matching call\ncounts. Matching calls are marked as verified, which affects\n`fn.verifyNoMoreInteractions_`.\n",
+		$internal: true,
 		"fn.verify_": {
 			call: "_ext.Call_",
 			"strictMatch!": "boolean",
@@ -12079,11 +12081,11 @@ var mockInternalTelepact = [
 					reason: "union.VerificationFailure_"
 				}
 			}
-		],
-		_errors: "^errors\\.Validation_$"
+		]
 	},
 	{
 		"///": "Verify that no interactions have occurred with this mock or that all\ninteractions have been verified.\n",
+		$internal: true,
 		"fn.verifyNoMoreInteractions_": {
 		},
 		"->": [
@@ -12098,11 +12100,11 @@ var mockInternalTelepact = [
 					]
 				}
 			}
-		],
-		_errors: "^errors\\.Validation_$"
+		]
 	},
 	{
 		"///": "Clear all stub conditions.",
+		$internal: true,
 		"fn.clearStubs_": {
 		},
 		"->": [
@@ -12110,11 +12112,11 @@ var mockInternalTelepact = [
 				Ok_: {
 				}
 			}
-		],
-		_errors: "^errors\\.Validation_$"
+		]
 	},
 	{
 		"///": "Clear all call data.",
+		$internal: true,
 		"fn.clearCalls_": {
 		},
 		"->": [
@@ -12122,11 +12124,11 @@ var mockInternalTelepact = [
 				Ok_: {
 				}
 			}
-		],
-		_errors: "^errors\\.Validation_$"
+		]
 	},
 	{
 		"///": "Set the seed of the random generator.",
+		$internal: true,
 		"fn.setRandomSeed_": {
 			seed: "integer"
 		},
@@ -12135,8 +12137,7 @@ var mockInternalTelepact = [
 				Ok_: {
 				}
 			}
-		],
-		_errors: "^errors\\.Validation_$"
+		]
 	},
 	{
 		"errors.Mock_": [