Make code more unit-testable for user's apps

By doing a few things:
- Remove enums from @azure/functions-core api
- Expose constructors for context and request for use in unit tests
- Allow running in a "test mode" where the core api doesn't exist

Author: ejizba

src/InvocationContext.ts

@@ -2,8 +2,8 @@
 // Licensed under the MIT License.
 
 import * as types from '@azure/functions';
-import { RetryContext, TraceContext, TriggerMetadata } from '@azure/functions';
-import { RpcInvocationRequest, RpcLog } from '@azure/functions-core';
+import { InvocationContextInit, LogHandler, RetryContext, TraceContext, TriggerMetadata } from '@azure/functions';
+import { RpcInvocationRequest } from '@azure/functions-core';
 import { convertKeysToCamelCase } from './converters/convertKeysToCamelCase';
 import { fromRpcRetryContext, fromRpcTraceContext } from './converters/fromRpcContext';
 
@@ -15,50 +15,48 @@ export class InvocationContext implements types.InvocationContext {
     retryContext?: RetryContext;
     extraInputs: InvocationContextExtraInputs;
     extraOutputs: InvocationContextExtraOutputs;
-    #userLogCallback: UserLogCallback;
+    #userLogHandler: LogHandler;
 
-    constructor(functionName: string, request: RpcInvocationRequest, userLogCallback: UserLogCallback) {
-        this.invocationId = <string>request.invocationId;
-        this.functionName = functionName;
-        this.triggerMetadata = request.triggerMetadata ? convertKeysToCamelCase(request.triggerMetadata) : {};
-        if (request.retryContext) {
-            this.retryContext = fromRpcRetryContext(request.retryContext);
+    constructor(init: InvocationContextInit & RpcInvocationRequest) {
+        this.invocationId = init.invocationId;
+        this.functionName = init.functionName;
+        this.triggerMetadata = init.triggerMetadata ? convertKeysToCamelCase(init.triggerMetadata) : {};
+        if (init.retryContext) {
+            this.retryContext = fromRpcRetryContext(init.retryContext);
         }
-        if (request.traceContext) {
-            this.traceContext = fromRpcTraceContext(request.traceContext);
+        if (init.traceContext) {
+            this.traceContext = fromRpcTraceContext(init.traceContext);
         }
-        this.#userLogCallback = userLogCallback;
+        this.#userLogHandler = init.logHandler;
         this.extraInputs = new InvocationContextExtraInputs();
         this.extraOutputs = new InvocationContextExtraOutputs();
     }
 
     log(...args: unknown[]): void {
-        this.#userLogCallback(RpcLog.Level.Information, ...args);
+        this.#userLogHandler('information', ...args);
     }
 
     trace(...args: unknown[]): void {
-        this.#userLogCallback(RpcLog.Level.Trace, ...args);
+        this.#userLogHandler('trace', ...args);
     }
 
     debug(...args: unknown[]): void {
-        this.#userLogCallback(RpcLog.Level.Debug, ...args);
+        this.#userLogHandler('debug', ...args);
     }
 
     info(...args: unknown[]): void {
-        this.#userLogCallback(RpcLog.Level.Information, ...args);
+        this.#userLogHandler('information', ...args);
     }
 
     warn(...args: unknown[]): void {
-        this.#userLogCallback(RpcLog.Level.Warning, ...args);
+        this.#userLogHandler('warning', ...args);
     }
 
     error(...args: unknown[]): void {
-        this.#userLogCallback(RpcLog.Level.Error, ...args);
+        this.#userLogHandler('error', ...args);
     }
 }
 
-type UserLogCallback = (level: RpcLog.Level, ...args: unknown[]) => void;
-
 class InvocationContextExtraInputs implements types.InvocationContextExtraInputs {
     #inputs: Record<string, unknown> = {};
     get(inputOrName: types.FunctionInput | string): any {

src/InvocationModel.ts

@@ -8,7 +8,8 @@ import {
     InvocationArguments,
     RpcBindingInfo,
     RpcInvocationResponse,
-    RpcLog,
+    RpcLogCategory,
+    RpcLogLevel,
     RpcTypedData,
 } from '@azure/functions-core';
 import { format } from 'util';
@@ -35,11 +36,12 @@ export class InvocationModel implements coreTypes.InvocationModel {
 
     // eslint-disable-next-line @typescript-eslint/require-await
     async getArguments(): Promise<InvocationArguments> {
-        const context = new InvocationContext(
-            this.#functionName,
-            this.#coreCtx.request,
-            (level: RpcLog.Level, ...args: unknown[]) => this.#userLog(level, ...args)
-        );
+        const context = new InvocationContext({
+            ...this.#coreCtx.request,
+            invocationId: nonNullProp(this.#coreCtx, 'invocationId'),
+            functionName: this.#functionName,
+            logHandler: (level: RpcLogLevel, ...args: unknown[]) => this.#userLog(level, ...args),
+        });
 
         const inputs: any[] = [];
         if (this.#coreCtx.request.inputData) {
@@ -83,7 +85,7 @@ export class InvocationModel implements coreTypes.InvocationModel {
 
         response.outputData = [];
         for (const [name, binding] of Object.entries(this.#bindings)) {
-            if (binding.direction === RpcBindingInfo.Direction.out) {
+            if (binding.direction === 'out') {
                 if (name === returnBindingKey) {
                     response.returnValue = this.#convertOutput(binding, result);
                 } else {
@@ -106,21 +108,21 @@ export class InvocationModel implements coreTypes.InvocationModel {
         }
     }
 
-    #log(level: RpcLog.Level, logCategory: RpcLog.RpcLogCategory, ...args: unknown[]): void {
+    #log(level: RpcLogLevel, logCategory: RpcLogCategory, ...args: unknown[]): void {
         this.#coreCtx.log(level, logCategory, format(...args));
     }
 
-    #systemLog(level: RpcLog.Level, ...args: unknown[]) {
-        this.#log(level, RpcLog.RpcLogCategory.System, ...args);
+    #systemLog(level: RpcLogLevel, ...args: unknown[]) {
+        this.#log(level, 'system', ...args);
     }
 
-    #userLog(level: RpcLog.Level, ...args: unknown[]): void {
+    #userLog(level: RpcLogLevel, ...args: unknown[]): void {
         if (this.#isDone && this.#coreCtx.state !== 'postInvocationHooks') {
             let badAsyncMsg =
                 "Warning: Unexpected call to 'log' on the context object after function execution has completed. Please check for asynchronous calls that are not awaited. ";
             badAsyncMsg += `Function name: ${this.#functionName}. Invocation Id: ${this.#coreCtx.invocationId}.`;
-            this.#systemLog(RpcLog.Level.Warning, badAsyncMsg);
+            this.#systemLog('warning', badAsyncMsg);
         }
-        this.#log(level, RpcLog.RpcLogCategory.User, ...args);
+        this.#log(level, 'user', ...args);
     }
 }

src/converters/toRpcHttpCookie.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 
 import { Cookie } from '@azure/functions';
-import { RpcHttpCookie } from '@azure/functions-core';
+import { RpcHttpCookie, RpcHttpCookieSameSite } from '@azure/functions-core';
 import { toNullableBool, toNullableDouble, toNullableString, toNullableTimestamp, toRpcString } from './toRpcNullable';
 
 /**
@@ -11,15 +11,15 @@ import { toNullableBool, toNullableDouble, toNullableString, toNullableTimestamp
  */
 export function toRpcHttpCookie(inputCookie: Cookie): RpcHttpCookie {
     // Resolve RpcHttpCookie.SameSite enum, a one-off
-    let rpcSameSite: RpcHttpCookie.SameSite = RpcHttpCookie.SameSite.None;
+    let rpcSameSite: RpcHttpCookieSameSite = 'none';
     if (inputCookie && inputCookie.sameSite) {
         const sameSite = inputCookie.sameSite.toLocaleLowerCase();
         if (sameSite === 'lax') {
-            rpcSameSite = RpcHttpCookie.SameSite.Lax;
+            rpcSameSite = 'lax';
         } else if (sameSite === 'strict') {
-            rpcSameSite = RpcHttpCookie.SameSite.Strict;
+            rpcSameSite = 'strict';
         } else if (sameSite === 'none') {
-            rpcSameSite = RpcHttpCookie.SameSite.ExplicitNone;
+            rpcSameSite = 'explicitNone';
         }
     }
 

src/http/HttpRequest.ts

@@ -23,11 +23,17 @@ export class HttpRequest implements types.HttpRequest {
 
     #cachedUser?: HttpRequestUser | null;
     #uReq: uRequest;
-    #body?: Buffer;
+    #body?: Buffer | string;
 
     constructor(rpcHttp: RpcHttpData) {
         const url = nonNullProp(rpcHttp, 'url');
-        this.#body = rpcHttp.body?.bytes ? Buffer.from(rpcHttp.body?.bytes) : undefined;
+
+        if (rpcHttp.body?.bytes) {
+            this.#body = Buffer.from(rpcHttp.body?.bytes);
+        } else if (rpcHttp.body?.string) {
+            this.#body = rpcHttp.body.string;
+        }
+
         this.#uReq = new uRequest(url, {
             body: this.#body,
             method: nonNullProp(rpcHttp, 'method'),

src/index.ts

@@ -46,17 +46,23 @@ import {
     TimerTriggerOptions,
 } from '@azure/functions';
 import * as coreTypes from '@azure/functions-core';
-import {
-    CoreInvocationContext,
-    FunctionCallback,
-    registerFunction,
-    RpcBindingInfo,
-    setProgrammingModel,
-} from '@azure/functions-core';
+import { CoreInvocationContext, FunctionCallback } from '@azure/functions-core';
 import { returnBindingKey, version } from './constants';
 import { InvocationModel } from './InvocationModel';
 import { getRandomHexString } from './utils/getRandomHexString';
 
+export { HttpRequest } from './http/HttpRequest';
+export { InvocationContext } from './InvocationContext';
+
+function tryGetCoreApiLazy(): typeof coreTypes | undefined {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        return <typeof coreTypes>require('@azure/functions-core');
+    } catch {
+        return undefined;
+    }
+}
+
 class ProgrammingModel implements coreTypes.ProgrammingModel {
     name = '@azure/functions';
     version = version;
@@ -67,7 +73,14 @@ class ProgrammingModel implements coreTypes.ProgrammingModel {
 
 let hasSetup = false;
 function setup() {
-    setProgrammingModel(new ProgrammingModel());
+    const coreApi = tryGetCoreApiLazy();
+    if (!coreApi) {
+        console.warn(
+            'WARNING: Failed to detect the Azure Functions runtime. Switching "@azure/functions" package to test mode - not all features are supported.'
+        );
+    } else {
+        coreApi.setProgrammingModel(new ProgrammingModel());
+    }
     hasSetup = true;
 }
 
@@ -193,20 +206,20 @@ export namespace app {
             setup();
         }
 
-        const bindings = {};
+        const bindings: Record<string, coreTypes.RpcBindingInfo> = {};
 
         const trigger = options.trigger;
         bindings[trigger.name] = {
             ...trigger,
-            direction: RpcBindingInfo.Direction.in,
+            direction: 'in',
             type: /trigger$/i.test(trigger.type) ? trigger.type : trigger.type + 'Trigger',
         };
 
         if (options.extraInputs) {
             for (const input of options.extraInputs) {
                 bindings[input.name] = {
                     ...input,
-                    direction: RpcBindingInfo.Direction.in,
+                    direction: 'in',
                 };
             }
         }
@@ -215,20 +228,27 @@ export namespace app {
             options.return.name = returnBindingKey;
             bindings[options.return.name] = {
                 ...options.return,
-                direction: RpcBindingInfo.Direction.out,
+                direction: 'out',
             };
         }
 
         if (options.extraOutputs) {
             for (const output of options.extraOutputs) {
                 bindings[output.name] = {
                     ...output,
-                    direction: RpcBindingInfo.Direction.out,
+                    direction: 'out',
                 };
             }
         }
 
-        registerFunction({ name, bindings }, <FunctionCallback>options.handler);
+        const coreApi = tryGetCoreApiLazy();
+        if (!coreApi) {
+            console.warn(
+                `WARNING: Skipping call to register function "${name}" because the "@azure/functions" package is in test mode.`
+            );
+        } else {
+            coreApi.registerFunction({ name, bindings }, <FunctionCallback>options.handler);
+        }
     }
 }
 

test/converters/toRpcHttpCookie.test.ts

@@ -2,7 +2,6 @@
 // Licensed under the MIT License.
 
 import { Cookie } from '@azure/functions';
-import { RpcHttpCookie } from '@azure/functions-core';
 import { expect } from 'chai';
 import 'mocha';
 import { toRpcHttpCookie } from '../../src/converters/toRpcHttpCookie';
@@ -68,16 +67,16 @@ describe('toRpcHttpCookie', () => {
 
         const rpcCookies = cookieInputs.map(toRpcHttpCookie);
         expect(rpcCookies[0].name).to.equal('none-cookie');
-        expect(rpcCookies[0].sameSite).to.equal(RpcHttpCookie.SameSite.ExplicitNone);
+        expect(rpcCookies[0].sameSite).to.equal('explicitNone');
 
         expect(rpcCookies[1].name).to.equal('lax-cookie');
-        expect(rpcCookies[1].sameSite).to.equal(RpcHttpCookie.SameSite.Lax);
+        expect(rpcCookies[1].sameSite).to.equal('lax');
 
         expect(rpcCookies[2].name).to.equal('strict-cookie');
-        expect(rpcCookies[2].sameSite).to.equal(RpcHttpCookie.SameSite.Strict);
+        expect(rpcCookies[2].sameSite).to.equal('strict');
 
         expect(rpcCookies[3].name).to.equal('default-cookie');
-        expect(rpcCookies[3].sameSite).to.equal(RpcHttpCookie.SameSite.None);
+        expect(rpcCookies[3].sameSite).to.equal('none');
     });
 
     it('throws on invalid input', () => {

test/index.ts

@@ -4,12 +4,9 @@
 import * as globby from 'globby';
 import * as Mocha from 'mocha';
 import * as path from 'path';
-import { setupTestCoreApi } from './setupTestCoreApi';
 
 export async function run(): Promise<void> {
     try {
-        setupTestCoreApi();
-
         const options: Mocha.MochaOptions = {
             color: true,
             reporter: 'mocha-multi-reporters',