@teamkeel/functions-runtime 0.0.1

package/src/errors.js

@@ -0,0 +1,116 @@
+const { createJSONRPCErrorResponse } = require("json-rpc-2.0");
+const { PermissionError } = require("./permissions");
+
+const RuntimeErrors = {
+  // Catchall error type for unhandled execution errors during custom function
+  UnknownError: -32001,
+  // DatabaseError represents any error at pg level that isn't handled explicitly below
+  DatabaseError: -32002,
+  // No result returned from custom function by user
+  NoResultError: -32003,
+  // When trying to delete/update a non existent record in the db
+  RecordNotFoundError: -32004,
+  ForeignKeyConstraintError: -32005,
+  NotNullConstraintError: -32006,
+  UniqueConstraintError: -32007,
+  PermissionError: -32008,
+};
+
+// errorToJSONRPCResponse transforms a JavaScript Error instance (or derivative) into a valid JSONRPC response object to pass back to the Keel runtime.
+function errorToJSONRPCResponse(request, e) {
+  if (!e.error) {
+    // it isnt wrapped
+
+    if (e instanceof PermissionError) {
+      return createJSONRPCErrorResponse(
+        request.id,
+        RuntimeErrors.PermissionError,
+        e.message
+      );
+    }
+
+    return createJSONRPCErrorResponse(
+      request.id,
+      RuntimeErrors.UnknownError,
+      e.message
+    );
+  }
+  // we want to switch on instanceof but there is no way to do that in js, so best to check the constructor class of the error
+  switch (e.error.constructor.name) {
+    // Any error thrown in the ModelAPI class is
+    // wrapped in a DatabaseError in order to differentiate 'our code' vs the user's own code.
+    case "NoResultError":
+      return createJSONRPCErrorResponse(
+        request.id,
+
+        // to be matched to https://github.com/teamkeel/keel/blob/e3115ffe381bfc371d4f45bbf96a15072a994ce5/runtime/actions/update.go#L54-L54
+        RuntimeErrors.RecordNotFoundError,
+        e.message
+      );
+    case "DatabaseError":
+      const { error: originalError } = e;
+
+      // if the originalError responds to 'code' then assume it has other pg error message keys
+      // todo: make this more ironclad.
+      // when using lib-pq, should match https://github.com/brianc/node-postgres/blob/master/packages/pg-protocol/src/parser.ts#L371-L386
+      if ("code" in originalError) {
+        const { code, detail, table } = originalError;
+
+        let rpcErrorCode, column, value;
+        const [col, val] = parseKeyMessage(originalError.detail);
+        column = col;
+        value = val;
+
+        switch (code) {
+          case "23502":
+            rpcErrorCode = RuntimeErrors.NotNullConstraintError;
+            column = originalError.column;
+            break;
+          case "23503":
+            rpcErrorCode = RuntimeErrors.ForeignKeyConstraintError;
+            break;
+          case "23505":
+            rpcErrorCode = RuntimeErrors.UniqueConstraintError;
+            break;
+          default:
+            rpcErrorCode = RuntimeErrors.DatabaseError;
+            break;
+        }
+
+        return createJSONRPCErrorResponse(request.id, rpcErrorCode, e.message, {
+          table,
+          column,
+          code,
+          detail,
+          value,
+        });
+      }
+
+      // we don't know what it is, but it's something else
+      return createJSONRPCErrorResponse(
+        request.id,
+        RuntimeErrors.DatabaseError,
+        e.message
+      );
+    default:
+      return createJSONRPCErrorResponse(
+        request.id,
+        RuntimeErrors.UnknownError,
+        e.message
+      );
+  }
+}
+
+// example data:
+// Key (author_id)=(fake) is not present in table "author".
+const keyMessagePattern = /\Key\s[(](.*)[)][=][(](.*)[)]/;
+const parseKeyMessage = (msg) => {
+  const [, col, value] = keyMessagePattern.exec(msg) || [];
+
+  return [col, value];
+};
+
+module.exports = {
+  errorToJSONRPCResponse,
+  RuntimeErrors,
+};

package/src/handleJob.js

@@ -0,0 +1,100 @@
+const {
+  createJSONRPCErrorResponse,
+  createJSONRPCSuccessResponse,
+  JSONRPCErrorCode,
+} = require("json-rpc-2.0");
+const { getDatabaseClient } = require("./database");
+const { tryExecuteFunction } = require("./tryExecuteFunction");
+const { errorToJSONRPCResponse, RuntimeErrors } = require("./errors");
+const opentelemetry = require("@opentelemetry/api");
+const { withSpan } = require("./tracing");
+const { PROTO_ACTION_TYPES } = require("./consts");
+
+// Generic handler function that is agnostic to runtime environment (local or lambda)
+// to execute a job function based on the contents of a jsonrpc-2.0 payload object.
+// To read more about jsonrpc request and response shapes, please read https://www.jsonrpc.org/specification
+async function handleJob(request, config) {
+  // Try to extract trace context from caller
+  const activeContext = opentelemetry.propagation.extract(
+    opentelemetry.context.active(),
+    request.meta?.tracing
+  );
+
+  // Run the whole request with the extracted context
+  return opentelemetry.context.with(activeContext, () => {
+    // Wrapping span for the whole request
+    return withSpan(request.method, async (span) => {
+      try {
+        const { createJobContextAPI, jobs } = config;
+
+        if (!(request.method in jobs)) {
+          const message = `no corresponding job found for '${request.method}'`;
+          span.setStatus({
+            code: opentelemetry.SpanStatusCode.ERROR,
+            message: message,
+          });
+          return createJSONRPCErrorResponse(
+            request.id,
+            JSONRPCErrorCode.MethodNotFound,
+            message
+          );
+        }
+
+        // The ctx argument passed into the job function.
+        const ctx = createJobContextAPI({
+          meta: request.meta,
+        });
+
+        const permitted =
+          request.meta && request.meta.permissionState.status === "granted"
+            ? true
+            : null;
+
+        const db = getDatabaseClient();
+        const jobFunction = jobs[request.method];
+        const actionType = PROTO_ACTION_TYPES.JOB;
+        const permissionFns = new Object();
+
+        // Jobs will have no permission functions yet.
+        permissionFns[request.method] = [];
+
+        const result = await tryExecuteFunction(
+          { request, ctx, permissionFns, permitted, db, actionType },
+          async () => {
+            // Return the job function to the containing tryExecuteFunction block
+            return jobFunction(ctx, request.params);
+          }
+        );
+
+        return createJSONRPCSuccessResponse(request.id, null);
+      } catch (e) {
+        if (e instanceof Error) {
+          span.recordException(e);
+          span.setStatus({
+            code: opentelemetry.SpanStatusCode.ERROR,
+            message: e.message,
+          });
+          return errorToJSONRPCResponse(request, e);
+        }
+
+        const message = JSON.stringify(e);
+
+        span.setStatus({
+          code: opentelemetry.SpanStatusCode.ERROR,
+          message: message,
+        });
+
+        return createJSONRPCErrorResponse(
+          request.id,
+          RuntimeErrors.UnknownError,
+          message
+        );
+      }
+    });
+  });
+}
+
+module.exports = {
+  handleJob,
+  RuntimeErrors,
+};

package/src/handleJob.test.js

@@ -0,0 +1,271 @@
+import { createJSONRPCRequest, JSONRPCErrorCode } from "json-rpc-2.0";
+import { sql } from "kysely";
+import { handleJob, RuntimeErrors } from "./handleJob";
+import { test, expect, beforeEach, describe } from "vitest";
+import { ModelAPI } from "./ModelAPI";
+import { useDatabase } from "./database";
+const { Permissions } = require("./permissions");
+import KSUID from "ksuid";
+
+test("when the job returns nothing as expected", async () => {
+  const config = {
+    jobs: {
+      myJob: async (ctx, inputs) => {},
+    },
+    createJobContextAPI: () => {},
+    permissions: {},
+  };
+
+  const rpcReq = createJSONRPCRequest("123", "myJob", { title: "a post" });
+  rpcReq.meta = { permissionState: { status: "granted", reason: "role" } };
+
+  expect(await handleJob(rpcReq, config)).toEqual({
+    id: "123",
+    jsonrpc: "2.0",
+    result: null,
+  });
+});
+
+test("when there is an unexpected error in the job", async () => {
+  const config = {
+    jobs: {
+      myJob: async (ctx, inputs) => {
+        throw new Error("oopsie daisy");
+      },
+    },
+    createJobContextAPI: () => {},
+  };
+
+  const rpcReq = createJSONRPCRequest("123", "myJob", { title: "a post" });
+  rpcReq.meta = { permissionState: { status: "granted", reason: "role" } };
+
+  expect(await handleJob(rpcReq, config)).toEqual({
+    id: "123",
+    jsonrpc: "2.0",
+    error: {
+      code: RuntimeErrors.UnknownError,
+      message: "oopsie daisy",
+    },
+  });
+});
+
+test("when there is an unexpected object thrown in the job", async () => {
+  const config = {
+    jobs: {
+      myJob: async (ctx, inputs) => {
+        throw { err: "oopsie daisy" };
+      },
+    },
+    createJobContextAPI: () => {},
+  };
+
+  const rpcReq = createJSONRPCRequest("123", "myJob", { title: "a post" });
+  rpcReq.meta = { permissionState: { status: "granted", reason: "role" } };
+
+  expect(await handleJob(rpcReq, config)).toEqual({
+    id: "123",
+    jsonrpc: "2.0",
+    error: {
+      code: RuntimeErrors.UnknownError,
+      message: '{"err":"oopsie daisy"}',
+    },
+  });
+});
+
+test("when there is no matching job for the path", async () => {
+  const config = {
+    jobs: {
+      myJob: async (ctx, inputs) => {},
+    },
+    createJobContextAPI: () => {},
+  };
+
+  const rpcReq = createJSONRPCRequest("123", "unknown", { title: "a post" });
+
+  expect(await handleJob(rpcReq, config)).toEqual({
+    id: "123",
+    jsonrpc: "2.0",
+    error: {
+      code: JSONRPCErrorCode.MethodNotFound,
+      message: "no corresponding job found for 'unknown'",
+    },
+  });
+});
+
+// The following tests assert on the various
+// jsonrpc responses that *should* happen when a user
+// writes a job that inadvertently causes a pg constraint error to occur inside of our ModelAPI class instance.
+describe("ModelAPI error handling", () => {
+  let functionConfig;
+  let db;
+
+  beforeEach(async () => {
+    process.env.KEEL_DB_CONN_TYPE = "pg";
+    process.env.KEEL_DB_CONN = `postgresql://postgres:postgres@localhost:5432/functions-runtime`;
+
+    db = useDatabase();
+
+    await sql`
+      DROP TABLE IF EXISTS post;
+      DROP TABLE IF EXISTS author;
+  
+      CREATE TABLE author(
+        "id"               text PRIMARY KEY,
+        "name"             text NOT NULL
+      );
+    
+      CREATE TABLE post(
+        "id"            text PRIMARY KEY,
+        "title"         text NOT NULL UNIQUE,
+        "author_id"     text NOT NULL REFERENCES author(id)
+      );
+      `.execute(db);
+
+    await sql`
+        INSERT INTO author (id, name) VALUES ('123', 'Bob')
+      `.execute(db);
+
+    const models = {
+      post: new ModelAPI("post", undefined, {
+        post: {
+          author: {
+            relationshipType: "belongsTo",
+            foreignKey: "author_id",
+            referencesTable: "person",
+          },
+        },
+      }),
+    };
+
+    functionConfig = {
+      jobs: {
+        createPost: async (ctx, inputs) => {
+          const post = await models.post.create({
+            id: KSUID.randomSync().string,
+            ...inputs,
+          });
+          return post;
+        },
+        deletePost: async (ctx, inputs) => {
+          const deleted = await models.post.delete(inputs);
+          return deleted;
+        },
+      },
+      createJobContextAPI: () => ({}),
+    };
+  });
+
+  test("when kysely returns a no result error", async () => {
+    // a kysely NoResultError is thrown when attempting to delete/update a non existent record.
+    const rpcReq = createJSONRPCRequest("123", "deletePost", {
+      id: "non-existent-id",
+    });
+    rpcReq.meta = { permissionState: { status: "granted", reason: "role" } };
+
+    expect(await handleJob(rpcReq, functionConfig)).toEqual({
+      id: "123",
+      jsonrpc: "2.0",
+      error: {
+        code: RuntimeErrors.RecordNotFoundError,
+        message: "no result",
+      },
+    });
+  });
+
+  test("when there is a not null constraint error", async () => {
+    const rpcReq = createJSONRPCRequest("123", "createPost", { title: null });
+    rpcReq.meta = { permissionState: { status: "granted", reason: "role" } };
+
+    expect(await handleJob(rpcReq, functionConfig)).toEqual({
+      id: "123",
+      jsonrpc: "2.0",
+      error: {
+        code: RuntimeErrors.NotNullConstraintError,
+        message: 'null value in column "title" violates not-null constraint',
+        data: {
+          code: "23502",
+          column: "title",
+          detail: expect.stringContaining("Failing row contains"),
+          table: "post",
+        },
+      },
+    });
+  });
+
+  test("when there is a uniqueness constraint error", async () => {
+    await sql`
+      INSERT INTO post (id, title, author_id) values(${
+        KSUID.randomSync().string
+      }, 'hello', '123')
+      `.execute(db);
+
+    const rpcReq = createJSONRPCRequest("123", "createPost", {
+      title: "hello",
+      author_id: "something",
+    });
+    rpcReq.meta = { permissionState: { status: "granted", reason: "role" } };
+
+    expect(await handleJob(rpcReq, functionConfig)).toEqual({
+      id: "123",
+      jsonrpc: "2.0",
+      error: {
+        code: RuntimeErrors.UniqueConstraintError,
+        message:
+          'duplicate key value violates unique constraint "post_title_key"',
+        data: {
+          code: "23505",
+          column: "title",
+          detail: "Key (title)=(hello) already exists.",
+          table: "post",
+          value: "hello",
+        },
+      },
+    });
+  });
+
+  test("when there is a null value in a foreign key column", async () => {
+    const rpcReq = createJSONRPCRequest("123", "createPost", { title: "123" });
+    rpcReq.meta = { permissionState: { status: "granted", reason: "role" } };
+
+    expect(await handleJob(rpcReq, functionConfig)).toEqual({
+      id: "123",
+      jsonrpc: "2.0",
+      error: {
+        code: RuntimeErrors.NotNullConstraintError,
+        message:
+          'null value in column "author_id" violates not-null constraint',
+        data: {
+          code: "23502",
+          column: "author_id",
+          detail: expect.stringContaining("Failing row contains"),
+          table: "post",
+        },
+      },
+    });
+  });
+
+  test("when there is a foreign key constraint violation", async () => {
+    const rpcReq = createJSONRPCRequest("123", "createPost", {
+      title: "123",
+      author_id: "fake",
+    });
+    rpcReq.meta = { permissionState: { status: "granted", reason: "role" } };
+
+    expect(await handleJob(rpcReq, functionConfig)).toEqual({
+      id: "123",
+      jsonrpc: "2.0",
+      error: {
+        code: RuntimeErrors.ForeignKeyConstraintError,
+        message:
+          'insert or update on table "post" violates foreign key constraint "post_author_id_fkey"',
+        data: {
+          code: "23503",
+          column: "author_id",
+          detail: 'Key (author_id)=(fake) is not present in table "author".',
+          table: "post",
+          value: "fake",
+        },
+      },
+    });
+  });
+});

package/src/handleRequest.js

@@ -0,0 +1,124 @@
+const {
+  createJSONRPCErrorResponse,
+  createJSONRPCSuccessResponse,
+  JSONRPCErrorCode,
+} = require("json-rpc-2.0");
+const { getDatabaseClient } = require("./database");
+const { tryExecuteFunction } = require("./tryExecuteFunction");
+const { errorToJSONRPCResponse, RuntimeErrors } = require("./errors");
+const opentelemetry = require("@opentelemetry/api");
+const { withSpan } = require("./tracing");
+
+// Generic handler function that is agnostic to runtime environment (local or lambda)
+// to execute a custom function based on the contents of a jsonrpc-2.0 payload object.
+// To read more about jsonrpc request and response shapes, please read https://www.jsonrpc.org/specification
+async function handleRequest(request, config) {
+  // Try to extract trace context from caller
+  const activeContext = opentelemetry.propagation.extract(
+    opentelemetry.context.active(),
+    request.meta?.tracing
+  );
+
+  // Run the whole request with the extracted context
+  return opentelemetry.context.with(activeContext, () => {
+    // Wrapping span for the whole request
+    return withSpan(request.method, async (span) => {
+      try {
+        const { createContextAPI, functions, permissionFns, actionTypes } =
+          config;
+
+        if (!(request.method in functions)) {
+          const message = `no corresponding function found for '${request.method}'`;
+          span.setStatus({
+            code: opentelemetry.SpanStatusCode.ERROR,
+            message: message,
+          });
+          return createJSONRPCErrorResponse(
+            request.id,
+            JSONRPCErrorCode.MethodNotFound,
+            message
+          );
+        }
+
+        // headers reference passed to custom function where object data can be modified
+        const headers = new Headers();
+
+        // The ctx argument passed into the custom function.
+        const ctx = createContextAPI({
+          responseHeaders: headers,
+          meta: request.meta,
+        });
+
+        // The Go runtime does *some* permissions checks up front before the request reaches
+        // this method, so we pass in a permissionState object on the request.meta object that
+        // indicates whether a call to a custom function has already been authorised
+        const permitted =
+          request.meta && request.meta.permissionState.status === "granted"
+            ? true
+            : null;
+
+        const db = getDatabaseClient();
+        const customFunction = functions[request.method];
+        const actionType = actionTypes[request.method];
+
+        const result = await tryExecuteFunction(
+          { request, ctx, permitted, db, permissionFns, actionType },
+          async () => {
+            // Return the custom function to the containing tryExecuteFunction block
+            // Once the custom function is called, tryExecuteFunction will check the schema's permission rules to see if it can continue committing
+            // the transaction to the db. If a permission rule is violated, any changes made inside the transaction are rolled back.
+            return customFunction(ctx, request.params);
+          }
+        );
+
+        // Sometimes a custom function may be coded in such a way that nothing is returned from it.
+        // We see this as an error so handle accordingly.
+        if (result === undefined) {
+          // no result returned from custom function
+          return createJSONRPCErrorResponse(
+            request.id,
+            RuntimeErrors.NoResultError,
+            `no result returned from function '${request.method}'`
+          );
+        }
+
+        const response = createJSONRPCSuccessResponse(request.id, result);
+
+        const responseHeaders = {};
+        for (const pair of headers.entries()) {
+          responseHeaders[pair[0]] = pair[1].split(", ");
+        }
+        response.meta = { headers: responseHeaders };
+
+        return response;
+      } catch (e) {
+        if (e instanceof Error) {
+          span.recordException(e);
+          span.setStatus({
+            code: opentelemetry.SpanStatusCode.ERROR,
+            message: e.message,
+          });
+          return errorToJSONRPCResponse(request, e);
+        }
+
+        const message = JSON.stringify(e);
+
+        span.setStatus({
+          code: opentelemetry.SpanStatusCode.ERROR,
+          message: message,
+        });
+
+        return createJSONRPCErrorResponse(
+          request.id,
+          RuntimeErrors.UnknownError,
+          message
+        );
+      }
+    });
+  });
+}
+
+module.exports = {
+  handleRequest,
+  RuntimeErrors,
+};