Add basic hooks support (v4)

src/app.ts

@@ -2,6 +2,8 @@
 // Licensed under the MIT License.
 
 import {
+    AppStartHandler,
+    AppTerminateHandler,
     CosmosDBFunctionOptions,
     CosmosDBTrigger,
     EventGridFunctionOptions,
@@ -11,6 +13,9 @@ import {
     HttpHandler,
     HttpMethod,
     HttpMethodFunctionOptions,
+    InvocationContext,
+    PostInvocationHandler,
+    PreInvocationHandler,
     ServiceBusQueueFunctionOptions,
     ServiceBusTopicFunctionOptions,
     StorageBlobFunctionOptions,
@@ -21,6 +26,11 @@ import * as coreTypes from '@azure/functions-core';
 import { CoreInvocationContext, FunctionCallback } from '@azure/functions-core';
 import { InvocationModel } from './InvocationModel';
 import { returnBindingKey, version } from './constants';
+import { AppStartContext } from './hooks/AppStartContext';
+import { AppTerminateContext } from './hooks/AppTerminateContext';
+import { Disposable } from './hooks/Disposable';
+import { PostInvocationContext } from './hooks/PostInvocationContext';
+import { PreInvocationContext } from './hooks/PreInvocationContext';
 import * as output from './output';
 import * as trigger from './trigger';
 import { isTrigger } from './utils/isTrigger';
@@ -280,3 +290,72 @@ export function generic(name: string, options: FunctionOptions): void {
         coreApi.registerFunction({ name, bindings }, <FunctionCallback>options.handler);
     }
 }
+
+function coreRegisterHook(hookName: string, callback: coreTypes.HookCallback): coreTypes.Disposable {
+    const coreApi = tryGetCoreApiLazy();
+    if (!coreApi) {
+        console.warn(
+            `WARNING: Skipping call to register ${hookName} hook because the "@azure/functions" package is in test mode.`
+        );
+        return new Disposable(() => {
+            console.log(
+                `WARNING: Skipping call to dispose ${hookName} hook because the "@azure/functions" package is in test mode.`
+            );
+        });
+    } else {
+        return coreApi.registerHook(hookName, callback);
+    }
+}
+
+export function onStart(handler: AppStartHandler): Disposable {
+    const coreCallback: coreTypes.AppStartCallback = (coreContext: coreTypes.AppStartContext) => {
+        const context = new AppStartContext(coreContext);
+        return handler(context);
+    };
+    return coreRegisterHook('appStart', coreCallback as coreTypes.HookCallback);
+}
+
+export function onTerminate(handler: AppTerminateHandler): Disposable {
+    const coreCallback: coreTypes.AppTerminateCallback = (coreContext: coreTypes.AppTerminateContext) => {
+        const context = new AppTerminateContext(coreContext);
+        return handler(context);
+    };
+    return coreRegisterHook('appTerminate', coreCallback as coreTypes.HookCallback);
+}
+
+export function onPreInvocation(handler: PreInvocationHandler): Disposable {
+    const coreCallback: coreTypes.PreInvocationCallback = (coreContext: coreTypes.PreInvocationContext) => {
+        const invocationContext = coreContext.invocationContext as InvocationContext;
+        const preInvocContext = new PreInvocationContext({
+            // spreading here is necessary to pass hookData and appHookData objects
+            ...coreContext,
+            functionHandler: coreContext.functionCallback,
+            args: coreContext.inputs,
+            invocationContext,
+            coreContext,
+        });
+        return handler(preInvocContext);
+    };
+
+    return coreRegisterHook('preInvocation', coreCallback as coreTypes.HookCallback);
+}
+
+export function onPostInvocation(handler: PostInvocationHandler): Disposable {
+    const coreCallback: coreTypes.PostInvocationCallback = (coreContext: coreTypes.PostInvocationContext) => {
+        const invocationContext = coreContext.invocationContext as InvocationContext;
+        const postInvocContext = new PostInvocationContext({
+            // spreading here is necessary to pass hookData and appHookData objects
+            ...coreContext,
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            result: coreContext.result,
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            errorResult: coreContext.error,
+            args: coreContext.inputs,
+            invocationContext,
+            coreContext,
+        });
+        return handler(postInvocContext);
+    };
+
+    return coreRegisterHook('postInvocation', coreCallback as coreTypes.HookCallback);
+}

src/hooks/AppStartContext.ts

@@ -0,0 +1,16 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as types from '@azure/functions';
+import { AppStartContextInit } from '@azure/functions';
+import { HookContext } from './HookContext';
+
+export class AppStartContext extends HookContext implements types.AppStartContext {
+    functionAppDirectory: string;
+
+    constructor(init?: AppStartContextInit) {
+        super(init);
+        init = init || {};
+        this.functionAppDirectory = init.functionAppDirectory || 'unknown';
+    }
+}

src/hooks/AppTerminateContext.ts

@@ -0,0 +1,12 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as types from '@azure/functions';
+import { AppTerminateContextInit } from '@azure/functions';
+import { HookContext } from './HookContext';
+
+export class AppTerminateContext extends HookContext implements types.AppTerminateContext {
+    constructor(init?: AppTerminateContextInit) {
+        super(init);
+    }
+}

src/hooks/Disposable.ts

@@ -0,0 +1,35 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * Based off of the Node worker
+ * https://github.com/Azure/azure-functions-nodejs-worker/blob/bf28d9c5ad4ed22c5e42c082471d16108abee140/src/Disposable.ts
+ */
+export class Disposable {
+    static from(...inDisposables: { dispose(): any }[]): Disposable {
+        let disposables: ReadonlyArray<{ dispose(): any }> | undefined = inDisposables;
+        return new Disposable(function () {
+            if (disposables) {
+                for (const disposable of disposables) {
+                    if (disposable && typeof disposable.dispose === 'function') {
+                        disposable.dispose();
+                    }
+                }
+                disposables = undefined;
+            }
+        });
+    }
+
+    #callOnDispose?: () => any;
+
+    constructor(callOnDispose: () => any) {
+        this.#callOnDispose = callOnDispose;
+    }
+
+    dispose(): any {
+        if (this.#callOnDispose instanceof Function) {
+            this.#callOnDispose();
+            this.#callOnDispose = undefined;
+        }
+    }
+}

src/hooks/HookContext.ts

@@ -0,0 +1,35 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as types from '@azure/functions';
+import { HookContextInit, HookData } from '@azure/functions';
+
+export class HookContext implements types.HookContext {
+    #hookData: HookData;
+    #appHookData: HookData;
+
+    constructor(init?: HookContextInit) {
+        init = init || {};
+
+        // It's important to use the original objects passed in init (no copies or clones)
+        // because modifications to these objects are persisted by the worker
+        this.#hookData = init.hookData || {};
+        this.#appHookData = init.appHookData || {};
+    }
+
+    get(propertyName: string): unknown {
+        return this.#hookData[propertyName];
+    }
+
+    set(propertyName: string, value: unknown): void {
+        this.#hookData[propertyName] = value;
+    }
+
+    getGlobal(propertyName: string): unknown {
+        return this.#appHookData[propertyName];
+    }
+
+    setGlobal(propertyName: string, value: unknown): void {
+        this.#appHookData[propertyName] = value;
+    }
+}

src/hooks/InvocationHookContext.ts

@@ -0,0 +1,25 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as types from '@azure/functions';
+import { InvocationContext } from '../InvocationContext';
+import { ReadOnlyError } from '../errors';
+import { HookContext } from './HookContext';
+
+export abstract class InvocationHookContext extends HookContext implements types.InvocationHookContext {
+    #invocationContext: types.InvocationContext;
+
+    constructor(init?: types.InvocationHookContextInit) {
+        super(init);
+        init = init || {};
+        this.#invocationContext = init.invocationContext || new InvocationContext({});
+    }
+
+    get invocationContext(): types.InvocationContext {
+        return this.#invocationContext;
+    }
+
+    set invocationContext(_value: types.InvocationContext) {
+        throw new ReadOnlyError('invocationContext');
+    }
+}

src/hooks/PostInvocationContext.ts

@@ -0,0 +1,61 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as types from '@azure/functions';
+import { PostInvocationCoreContext } from '@azure/functions';
+import { InvocationHookContext } from './InvocationHookContext';
+
+export class PostInvocationContext extends InvocationHookContext implements types.PostInvocationContext {
+    #coreCtx: PostInvocationCoreContext;
+
+    constructor(init?: types.PostInvocationContextInit) {
+        super(init);
+        init = init || {};
+        if (!init.coreContext) {
+            init.coreContext = {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                result: typeof init.result === 'undefined' ? null : init.errorResult,
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                error: typeof init.errorResult === 'undefined' ? null : init.errorResult,
+                inputs: init.args || [],
+            };
+        }
+
+        this.#coreCtx = init.coreContext;
+    }
+
+    get args(): any[] {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this.#coreCtx.inputs;
+    }
+
+    set args(value: any[]) {
+        // it's important to use the core context inputs
+        // since changes to this array are persisted by the worker
+        this.#coreCtx.inputs = value;
+    }
+
+    get result(): any {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this.#coreCtx.result;
+    }
+
+    set result(value: any) {
+        // it's important to use the core context result
+        // since changes to this value are persisted by the worker
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        this.#coreCtx.result = value;
+    }
+
+    get errorResult(): any {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this.#coreCtx.error;
+    }
+
+    set errorResult(value: any) {
+        // it's important to use the core context result
+        // since changes to this value are persisted by the worker
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        this.#coreCtx.error = value;
+    }
+}

src/hooks/PreInvocationContext.ts

@@ -0,0 +1,44 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as types from '@azure/functions';
+import { FunctionHandler, PreInvocationContextInit, PreInvocationCoreContext } from '@azure/functions';
+import { InvocationHookContext } from './InvocationHookContext';
+
+export class PreInvocationContext extends InvocationHookContext implements types.PreInvocationContext {
+    #coreCtx: PreInvocationCoreContext;
+
+    constructor(init?: PreInvocationContextInit) {
+        super(init);
+        init = init || {};
+        if (!init.coreContext) {
+            init.coreContext = {
+                // eslint-disable-next-line @typescript-eslint/no-empty-function
+                functionCallback: init.functionHandler || (() => {}),
+                inputs: init.args || [],
+            };
+        }
+        this.#coreCtx = init.coreContext;
+    }
+
+    get functionHandler(): FunctionHandler {
+        return this.#coreCtx.functionCallback;
+    }
+
+    set functionHandler(value: FunctionHandler) {
+        // it's important to use the core context functionCallback
+        // since changes to this value are persisted by the worker
+        this.#coreCtx.functionCallback = value;
+    }
+
+    get args(): any[] {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this.#coreCtx.inputs;
+    }
+
+    set args(value: any[]) {
+        // it's important to use the core context inputs
+        // since changes to this array are persisted by the worker
+        this.#coreCtx.inputs = value;
+    }
+}

types/app.d.ts

@@ -4,6 +4,7 @@
 import { CosmosDBFunctionOptions } from './cosmosDB';
 import { EventGridFunctionOptions } from './eventGrid';
 import { EventHubFunctionOptions } from './eventHub';
+import { AppStartHandler, AppTerminateHandler, Disposable, PostInvocationHandler, PreInvocationHandler } from './hooks';
 import { HttpFunctionOptions, HttpHandler, HttpMethodFunctionOptions } from './http';
 import { FunctionOptions } from './index';
 import { ServiceBusQueueFunctionOptions, ServiceBusTopicFunctionOptions } from './serviceBus';
@@ -150,3 +151,39 @@ export function cosmosDB(name: string, options: CosmosDBFunctionOptions): void;
  * @param options Configuration options describing the inputs, outputs, and handler for this function
  */
 export function generic(name: string, options: FunctionOptions): void;
+
+/**
+ * Register a hook on the `appStart` event, executed at the start of your application
+ *
+ * @param handler the handler for the event
+ * @returns a `Disposable` object that can be used to unregister the hook
+ */
+export function onStart(handler: AppStartHandler): Disposable;
+
+/**
+ * Register a hook on the `appTerminate` event, executed during graceful shutdown of your application
+ * This hook will not be executed if your application is terminated forcefully
+ * Please note that all `appTerminate` hooks must finish execution in 10 seconds or less, or they will be terminated.
+
+ * @param handler the handler for the event
+ * @returns a `Disposable` object that can be used to unregister the hook
+ */
+export function onTerminate(handler: AppTerminateHandler): Disposable;
+
+/**
+ * Register a hook to be run right _before_ a function is invoked.
+ * This hook will be executed for all functions in your app.
+ *
+ * @param handler the handler for the event
+ * @returns a `Disposable` object that can be used to unregister the hook
+ */
+export function onPreInvocation(handler: PreInvocationHandler): Disposable;
+
+/**
+ * Register a hook to be run right _after_ a function is invoked.
+ * This hook will be executed for all functions in your app.
+ *
+ * @param handler the handler for the event
+ * @returns a `Disposable` object that can be used to unregister the hook
+ */
+export function onPostInvocation(handler: PostInvocationHandler): Disposable;