Initial version of order-processing-typescript sample

Signed-off-by: Gerhard Poul <gerhard.poul@oracle.com>

Author: gpoul

README.md

@@ -73,6 +73,7 @@ This repository provides examples demonstrating how to use Oracle Functions.
 |------------------------------------------------------|:------:|:----:|
 | Serverless SaaS Extensions using Oracle Functions, API Gateway and VBCS | [repo](https://github.com/oracle/cloud-asset-fusion-serverless-vbcs-sample) | [blog](https://www.ateam-oracle.com/the-cloud-native-approach-to-extending-your-saas-applications)
 | Function that demonstrates connectivity between Oracle SaaS applications with OIC | [sample](./samples/oci-oic-hcm-object-upload)|
+| TypeScript function migrated from AWS Lambda to OCI Functions | [sample](./samples/order-processing-typescript)|
 
 ## Documentation
 

samples/order-processing-typescript/Dockerfile

@@ -0,0 +1,15 @@
+FROM fnproject/node:20-dev as build-stage
+WORKDIR /function
+ADD package.json /function/
+ADD func.ts /function/
+RUN npm install  && chown -R $(id -u):$(id -g) node_modules && npm run build
+FROM fnproject/node:20
+WORKDIR /function
+# Might want to add package lock file also for prod builds
+ADD package.json /function/
+# Instead of copy node_modules we reinstall without dev dependencies to get a smaller image
+RUN npm install --omit=dev && chown -R $(id -u):$(id -g) node_modules && du -hs /function
+# Copy the built JavaScript sources from build-stage
+COPY --from=build-stage /function/dist/ /function/
+RUN chmod -R o+r /function
+ENTRYPOINT ["node", "--enable-source-maps", "func.js"]

samples/order-processing-typescript/README.md

@@ -0,0 +1,94 @@
+# Function receives an order JSON and creates an object in a bucket
+The JSON document type the function processes is defined in [func.ts](func.ts#L7-L11) and an example can be found in the guide below. The object is written to a target bucket configured through environment variables.
+
+As an alternative to the OCI Object Storage API this function also shows how to use the OCI Object Storage Amazon S3 Compatibility APIs. In production-usage you'd not use both at the same time, but we make it easy for testing purposes to change the used API through environment variables so you can experience both options.
+
+
+## Prerequisites
+Before you deploy this sample function, make sure you have run step A, B and C of the [Oracle Functions Quick Start Guide for Cloud Shell](https://www.oracle.com/webfolder/technetwork/tutorials/infographics/oci_functions_cloudshell_quickview/functions_quickview_top/functions_quickview/index.html)
+* A - Set up your tenancy
+* B - Create application
+* C - Set up your Cloud Shell dev environment
+
+
+## List Applications 
+Assuming you have successfully completed the prerequisites, you should see your application in the list of applications.
+```
+fn ls apps
+```
+
+
+## Create or Update your Dynamic Group
+In order to use other OCI Services, your function must be part of a dynamic group. For information on how to create a dynamic group, refer to the [documentation](https://docs.cloud.oracle.com/iaas/Content/Identity/Tasks/managingdynamicgroups.htm#To).
+
+When specifying the *Matching Rules*, we suggest matching all functions in a compartment with:
+```
+ALL {resource.type = 'fnfunc', resource.compartment.id = 'ocid1.compartment.oc1..aaaaaxxxxx'}
+```
+Please check the [Accessing Other Oracle Cloud Infrastructure Resources from Running Functions](https://docs.cloud.oracle.com/en-us/iaas/Content/Functions/Tasks/functionsaccessingociresources.htm) for other *Matching Rules* options.
+
+
+## Create or Update IAM Policies
+Create a new policy that allows the dynamic group to write to the target bucket.
+
+Your policy should look something like this:
+```
+Allow dynamic-group <dynamic-group-name> to use buckets in compartment <compartment-name>
+Allow dynamic-group <dynamic-group-name> to manage objects in compartment <compartment-name>
+```
+For more information on how to create policies, check the [documentation](https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/policysyntax.htm).
+
+
+## Review and customize your function
+Review the following files in the current folder:
+* the code of the function, [func.ts](./func.ts)
+* its dependencies, [package.json](./package.json)
+* its dockerfile, [Dockerfile](./Dockerfile)
+* the function metadata, [func.yaml](./func.yaml)
+
+
+## Set the function environment values
+The function requires the following environment values to be set:
+- OS_NAMESPACE, the value should be your tenancy's object storage namespace name
+
+Configure the value before deployment in the `func.yaml` file.
+
+
+## Deploy the function
+In Cloud Shell, run the fn deploy command to build the function and its dependencies as a Docker image,
+push the image to OCIR, and deploy the function to Oracle Functions in your application.
+
+```
+fn -v deploy --app <your app name>
+```
+e.g.
+```
+fn -v deploy --app myapp
+```
+
+
+## Invoke the function
+Invoke the function as follows:
+
+```
+echo -n '<JSON message>' | fn invoke <your app name> order-processing
+```
+e.g.:
+```
+echo -n '{"orderId": "43", "price": 43.99, "product": "Coffee Beans"}' | fn invoke order-processing-app order-processing
+```
+
+
+## Monitoring Functions
+
+Learn how to configure basic observability for your function using metrics, alarms and email alerts:
+* [Basic Guidance for Monitoring your Functions](../basic-observability/functions.md)
+
+
+## Writing to OCI Object Storage using the Amazon S3 Compatibility API
+To start using the OCI Object Storage Amazon S3 Compatibility API you need to set the following environment variables of the function:
+- TARGET_API, change the value from "OCI" to "S3" to switch the used API
+- AWS_ACCESS_KEY_ID, set this to the *Access key* of your created *Customer Secret Key*
+- AWS_SECRET_ACCESS_KEY, set this to the *Secret key* of your created *Customer Secret Key*
+
+Configure the value before deployment in the `func.yaml` file or after deployment through the OCI Console.

samples/order-processing-typescript/fn-fdk.d.ts

@@ -0,0 +1,242 @@
+declare module '@fnproject/fdk' {
+
+export function handle(fnfunction: fnHandler, options: object): () => void;
+export function streamResult(stream: any): StreamResult;
+export function rawResult(res: string | Buffer): RawResult;
+/**
+ * The function handler  - This is a user-supplied node function that implements the behaviour of the current fn function
+ */
+export type fnHandler = (the: any, the: Context) => string | number | Promise<any> | null | Response;
+declare class StreamResult extends FnResult {
+    constructor(stream: any);
+    _stream: any;
+    writeResult(ctx: any, resp: any): any;
+}
+declare class RawResult extends FnResult {
+    constructor(raw: any);
+    _raw: any;
+}
+/**
+ * Context is the function invocation context - it enables functions to read and write metadata from the request including event headers, config and the underlying payload
+ */
+declare class Context {
+    constructor(config: any, payload: any, headers: any);
+    _config: any;
+    _body: any;
+    _headers: any;
+    _responseHeaders: {};
+    /**
+     * Returns the deadline for the function invocation as a Date object
+     * @returns {Date}
+     */
+    get deadline(): Date;
+    /**
+     * returns the Fn Call ID associated with this call
+     * @returns {string}
+     */
+    get callID(): string;
+    /**
+     * Returns the application name associated with this function
+     * @returns {string}
+     */
+    get appName(): string;
+    /**
+     * Returns the application ID associated with this function
+     * @returns {string}
+     */
+    get appID(): string;
+    /**
+     * Returns the function name associated with this function
+     * @returns {string}
+     */
+    get fnName(): string;
+    /**
+     * Returns the function ID associated with this function
+     * @returns {string}
+     */
+    get fnID(): string;
+    /**
+     * Returns the amount of RAM (in MB) allocated to this function
+     * @returns {int}
+     */
+    get memory(): int;
+    /**
+     * Returns the application configuration for this function
+     * @returns {Object.<string,string>}
+     */
+    get config(): {
+        [x: string]: string;
+    };
+    /**
+     * Returns the raw body of the input to this function
+     * @returns {*}
+     */
+    get body(): any;
+    /**
+     * Returns the content type of the body (if set)
+     * @returns {null|string}
+     */
+    get contentType(): null | string;
+    /**
+     * returns a map of headers associated with this function this is an object containing key->[string] values
+     * Header keys are always canonicalized to HTTP first-caps style
+  
+     * This returns a copy of the underlying headers, changes to the response value will not be reflected in the function response
+     *
+     * @returns {Object.<string,Array.<string>>}
+     */
+    get headers(): {
+        [x: string]: string[];
+    };
+    /**
+     * Create an OCI APM TracingContext for the current invocation.
+     */
+    get tracingContext(): TracingContext;
+    /**
+     * returns a object containing the outbound  headers  associated with this function this is an object containing key->[string] values
+     *
+     * Header keys are always canonicalized to HTTP first-caps style
+     *
+     * This returns a copy of the underlying headers, changes to the response value will not be reflected in the function response
+     *
+     * @returns {Object.<string,Array.<string>>}
+     */
+    get responseHeaders(): {
+        [x: string]: string[];
+    };
+    /**
+     * returns all header values for a given key
+     * @param key {string}
+     * @returns {Array.<string>}
+     */
+    getAllHeaderValues(key: string): Array<string>;
+    /**
+     * Returns the first value of a given header or null
+     * Header keys are compared using case-insensitive matching
+     * @param key {string}
+     * @returns {string|null}
+     */
+    getHeader(key: string): string | null;
+    /**
+     * Returns a config value for a given key
+     * @param key  {string}
+     * @returns {string|null}
+     */
+    getConfig(key: string): string | null;
+    /**
+     * Returns the first value of a given header or null
+     * Header keys are compared using case-insensitive matching
+     * @param key {string}
+     * @returns {string|null}
+     */
+    getResponseHeader(key: string): string | null;
+    /**
+     * Sets a response header to zero or more values
+     * @param key {string}
+     * @param values {string}
+     */
+    setResponseHeader(key: string, ...values: string): void;
+    /**
+     * Appends a response header to any existing values
+     * @param key {string}
+     * @param values {string}
+     */
+    addResponseHeader(key: string, ...values: string): void;
+    /**
+     * Sets the response content type
+     * @param contentType {string}
+     */
+    set responseContentType(contentType: string);
+    /**
+     * Gets the response content type
+     * @returns {string|null}
+     */
+    get responseContentType(): string | null;
+    /**
+     * Returns the httpContext associated with this request
+     * @returns {HTTPGatewayContext}
+     */
+    get httpGateway(): HTTPGatewayContext;
+}
+/**
+ * A function result = this causes the handler wrapper to use a specific response writer
+ */
+declare class FnResult {
+    writeResult(ctx: any, resp: any): void;
+}
+/**
+ * TracingContext defines an OCI APM tracing context for the current invocation.
+ * Traces are currently defined by the Zipkin standard.
+ * See: https://zipkin.io/pages/instrumenting
+ */
+declare class TracingContext {
+    constructor(ctx: any);
+    isEnabled: boolean;
+    traceCollectorUrl: any;
+    traceId: any;
+    spanId: any;
+    parentSpanId: any;
+    sampled: boolean;
+    flags: any;
+    serviceName: string;
+}
+declare class HTTPGatewayContext {
+    /**
+     * Create an HTTP context
+     * @param ctx {Context}
+     */
+    constructor(ctx: Context);
+    ctx: Context;
+    _headers: {};
+    /**
+     * returns the HTTP request URL for this event
+     * @returns {string}
+     */
+    get requestURL(): string;
+    /**
+     * Returns the HTTP method for this event
+     * @returns {string}
+     */
+    get method(): string;
+    /**
+     * returns the HTTP headers received by the gateway for this event
+     * @returns {*}
+     */
+    get headers(): any;
+    /**
+     * Retuns a specific header or null if the header is not set - where multiple  values are present the first header is returned
+     * @param key {string} the header key
+     * @returns {string|null}
+     */
+    getHeader(key: string): string | null;
+    /**
+     * returns all header values for a given key
+     * @param key {string}
+     * @returns {Array.<string>}
+     */
+    getAllHeaderValues(key: string): Array<string>;
+    /**
+     * set the status code of the HTTP response
+     * @param status {int}
+     */
+    set statusCode(status: int);
+    /**
+     * Returns the HTTP status code of the HTTP response
+     * @returns {string}
+     */
+    get statusCode(): string;
+    /**
+     * Sets a response header to zero or more values
+     * @param key {string}
+     * @param values {string}
+     */
+    setResponseHeader(key: string, ...values: string): void;
+    /**
+     * Appends a response header to any existing values
+     * @param key {string}
+     * @param values {string}
+     */
+    addResponseHeader(key: string, ...values: string): void;
+}
+export {};
+}