feat: implement typed function signature

Author: garethgeorge

src/function_registry.ts

@@ -12,27 +12,34 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import {HttpFunction, CloudEventFunction, HandlerFunction} from './functions';
+import {
+  HttpFunction,
+  CloudEventFunction,
+  HandlerFunction,
+  TypedHandlerFunction,
+  InvocationFormat,
+  JsonInvocationSerializer,
+} from './functions';
 import {SignatureType} from './types';
 
-interface RegisteredFunction<T> {
+interface RegisteredFunction<T, U> {
   signatureType: SignatureType;
-  userFunction: HandlerFunction<T>;
+  userFunction: HandlerFunction<T, U>;
 }
 
 /**
  * Singleton map to hold the registered functions
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const registrationContainer = new Map<string, RegisteredFunction<any>>();
+const registrationContainer = new Map<string, RegisteredFunction<any, any>>();
 
 /**
  * Helper method to store a registered function in the registration container
  */
-const register = <T = unknown>(
+const register = <T = unknown, U = unknown>(
   functionName: string,
   signatureType: SignatureType,
-  userFunction: HandlerFunction<T>
+  userFunction: HandlerFunction<T, U>
 ): void => {
   if (!isValidFunctionName(functionName)) {
     throw new Error(`Invalid function name: ${functionName}`);
@@ -94,3 +101,18 @@ export const cloudEvent = <T = unknown>(
 ): void => {
   register(functionName, 'cloudevent', handler);
 };
+
+
+
+export const typed = <T, U>(
+  functionName: string,
+  handler: TypedHandlerFunction<T, U>['handler'] | TypedHandlerFunction<T, U>
+): void => {
+  if (handler instanceof Function) {
+    handler = {
+      handler,
+      format: new JsonInvocationSerializer<T, U>(),
+    }
+  }
+  register(functionName, 'typed', handler);
+};

src/function_wrappers.ts

@@ -26,6 +26,10 @@ import {
   CloudEventFunction,
   CloudEventFunctionWithCallback,
   HandlerFunction,
+  TypedHandlerFunction,
+  InvocationFormat,
+  InvocationRequest,
+  InvocationResponse
 } from './functions';
 import {CloudEvent} from './functions';
 import {SignatureType} from './types';
@@ -176,7 +180,7 @@ const wrapEventFunction = (userFunction: EventFunction): RequestHandler => {
 };
 
 /**
- * Wraps an callback style event function in an express RequestHandler.
+ * Wraps a callback style event function in an express RequestHandler.
  * @param userFunction User's function.
  * @return An Express hander function that invokes the user function.
  */
@@ -191,6 +195,68 @@ const wrapEventFunctionWithCallback = (
   return wrapHttpFunction(httpHandler);
 };
 
+/**
+ * Wraps a typed function in an express style RequestHandler.
+ * @param userFunction User's function
+ * @return An Express handler function that invokes the user function
+ */
+const wrapTypedFunction = (
+  typedFunction: TypedHandlerFunction
+): RequestHandler => {
+  class InvocationRequestImpl implements InvocationRequest {
+    constructor(private req: Request) {}
+    
+    body(): string | Buffer {
+      return this.req.body;
+    }
+    
+    header(header: string): string | undefined {
+      return this.req.header(header);
+    }
+  }
+
+  class InvocationResponseImpl implements InvocationResponse {
+    constructor(private req: Response) { }
+    
+    setHeader(key: string, value: string): void {
+      throw new Error('Method not implemented.');
+    }
+    write(data: string | Buffer): void {
+      this.req.write(data);
+    }
+    end(data: string | Buffer): void {
+      this.req.end(data);
+    }
+  }
+
+  const handler: HttpFunction = async (req: Request, res: Response) => {
+    let reqTyped: any;
+    try {
+      reqTyped = typedFunction.format.deserializeRequest(new InvocationRequestImpl(req));
+      if (reqTyped instanceof Promise) {
+        reqTyped = await reqTyped;
+      }
+    } catch (err) {
+      sendCrashResponse({
+        err, res,
+        statusOverride: 400 // 400 Bad Request
+      });
+    }
+
+    let resTyped: any = typedFunction.handler(reqTyped);
+    if (resTyped instanceof Promise) {
+      resTyped = await resTyped;
+    }
+
+    const maybePromise = typedFunction.format.serializeResponse(new InvocationResponseImpl(res), resTyped);
+    if (maybePromise instanceof Promise) {
+      await maybePromise;
+    }
+  }
+
+  return wrapHttpFunction(handler);
+}
+
 /**
  * Wraps a user function with the provided signature type in an express
  * RequestHandler.

src/functions.ts

@@ -74,16 +74,26 @@ export interface CloudEventFunction<T = unknown> {
 export interface CloudEventFunctionWithCallback<T = unknown> {
   (cloudEvent: CloudEvent<T>, callback: Function): any;
 }
+
+/**
+ * A Typed function handler that may return a value or a promise.
+ */
+export interface TypedHandlerFunction<T = unknown, U = unknown> {
+  handler: (req: T) => U | Promise<U>;
+  format: InvocationFormat<T, U>;
+}
+
 /**
  * A function handler.
  * @public
  */
-export type HandlerFunction<T = unknown> =
+export type HandlerFunction<T = unknown, U = unknown> =
   | HttpFunction
   | EventFunction
   | EventFunctionWithCallback
   | CloudEventFunction<T>
-  | CloudEventFunctionWithCallback<T>;
+  | CloudEventFunctionWithCallback<T>
+  | TypedHandlerFunction<T, U>;
 
 /**
  * A legacy event.
@@ -137,3 +147,51 @@ export interface CloudFunctionsContext {
  * @public
  */
 export type Context = CloudFunctionsContext | CloudEvent<unknown>;
+
+/**
+ * Invocation request interface describes the properties of an invocation.
+ */
+export interface InvocationRequest {
+  body(): string | Buffer;
+  header(header: string): string | undefined;
+}
+
+/**
+ * InvocationResponse interface describes the properties that can be set on
+ * an invocation response.
+ */
+export interface InvocationResponse {
+  setHeader(key: string, value: string): void;
+  write(data: string | Buffer): void;
+  end(data: string | Buffer): void;
+}
+
+export interface InvocationFormat<T, U> {
+  /**
+   * 
+   * @param request the request body as raw bytes
+   * @param headers the headers received on the HTTP request as a map
+   */
+  deserializeRequest(request: InvocationRequest): T | Promise<T>;
+  /**
+   *
+   * @param response
+   * @param responseHeaders mutable object providing headers that will be set on the response
+   */
+  serializeResponse(responseWriter: InvocationResponse, response: U): void | Promise<void>;
+}
+
+export class JsonInvocationSerializer<T, U> implements InvocationFormat<T, U> {
+  deserializeRequest(request: InvocationRequest): T {
+    if (!(typeof request.body === 'string')) {
+      throw new Error('Request Content-Type or encoding unsupported');
+    }
+    if
+    return JSON.parse(request.body);
+  }
+
+  serializeResponse(responseWriter: InvocationResponse, response: U): void {
+    responseWriter.setHeader('content-type', 'application/json');
+    responseWriter.end(JSON.stringify(response));
+  }
+}

src/logger.ts

@@ -28,13 +28,15 @@ export function sendCrashResponse({
   callback,
   silent = false,
   statusHeader = 'crash',
+  statusOverride = 500
 }: {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   err: Error | any;
   res: express.Response | null;
   callback?: Function;
   silent?: boolean;
   statusHeader?: string;
+  statusOverride?: number;
 }) {
   if (!silent) {
     console.error(err.stack || err);
@@ -48,10 +50,10 @@ export function sendCrashResponse({
     res.set(FUNCTION_STATUS_HEADER_FIELD, statusHeader);
 
     if (process.env.NODE_ENV !== 'production') {
-      res.status(500);
+      res.status(statusOverride);
       res.send((err.message || err) + '');
     } else {
-      res.sendStatus(500);
+      res.sendStatus(statusOverride);
     }
   }
   if (callback) {

src/server.ts

@@ -119,7 +119,7 @@ export function getServer(
   }
 
   if (functionSignatureType === 'http') {
-    app.use('/favicon.ico|/robots.txt', (req, res) => {
+    app.use('/favicon.ico|/robots.txt', (req: express.Request, res) => {
       // Neither crawlers nor browsers attempting to pull the icon find the body
       // contents particularly useful, so we send nothing in the response body.
       res.status(404).send(null);

src/types.ts

@@ -19,7 +19,7 @@ export const FUNCTION_STATUS_HEADER_FIELD = 'X-Google-Status';
 /**
  * List of function signature types that are supported by the framework.
  */
-export const SignatureType = ['http', 'event', 'cloudevent'] as const;
+export const SignatureType = ['http', 'event', 'cloudevent', 'typed'] as const;
 
 /**
  * Union type of all valid function SignatureType values.