@teamkeel/functions-runtime 0.0.1

package/src/handleRequest.test.js

@@ -0,0 +1,360 @@
+import { createJSONRPCRequest, JSONRPCErrorCode } from "json-rpc-2.0";
+import { sql } from "kysely";
+import { handleRequest, RuntimeErrors } from "./handleRequest";
+import { test, expect, beforeEach, describe } from "vitest";
+import { ModelAPI } from "./ModelAPI";
+import { useDatabase } from "./database";
+const { Permissions } = require("./permissions");
+import { PROTO_ACTION_TYPES } from "./consts";
+import KSUID from "ksuid";
+
+test("when the custom function returns expected value", async () => {
+  const config = {
+    functions: {
+      createPost: async (ctx, inputs) => {
+        new Permissions().allow();
+
+        return {
+          title: "a post",
+          id: "abcde",
+        };
+      },
+    },
+    actionTypes: {
+      createPost: PROTO_ACTION_TYPES.CREATE,
+    },
+    createContextAPI: () => {},
+  };
+
+  const rpcReq = createJSONRPCRequest("123", "createPost", { title: "a post" });
+
+  expect(await handleRequest(rpcReq, config)).toEqual({
+    id: "123",
+    jsonrpc: "2.0",
+    meta: {
+      headers: {},
+    },
+    result: {
+      title: "a post",
+      id: "abcde",
+    },
+  });
+});
+
+test("when the custom function doesnt return a value", async () => {
+  const config = {
+    functions: {
+      createPost: async (ctx, inputs) => {
+        new Permissions().allow();
+      },
+    },
+    permissions: {},
+    actionTypes: {
+      createPost: PROTO_ACTION_TYPES.CREATE,
+    },
+    createContextAPI: () => {},
+  };
+
+  const rpcReq = createJSONRPCRequest("123", "createPost", { title: "a post" });
+
+  expect(await handleRequest(rpcReq, config)).toEqual({
+    id: "123",
+    jsonrpc: "2.0",
+    error: {
+      code: RuntimeErrors.NoResultError,
+      message: "no result returned from function 'createPost'",
+    },
+  });
+});
+
+test("when there is no matching function for the path", async () => {
+  const config = {
+    functions: {
+      createPost: async (ctx, inputs) => {},
+    },
+    actionTypes: {
+      createPost: PROTO_ACTION_TYPES.CREATE,
+    },
+    createContextAPI: () => {},
+  };
+
+  const rpcReq = createJSONRPCRequest("123", "unknown", { title: "a post" });
+
+  expect(await handleRequest(rpcReq, config)).toEqual({
+    id: "123",
+    jsonrpc: "2.0",
+    error: {
+      code: JSONRPCErrorCode.MethodNotFound,
+      message: "no corresponding function found for 'unknown'",
+    },
+  });
+});
+
+test("when there is an unexpected error in the custom function", async () => {
+  const config = {
+    functions: {
+      createPost: async (ctx, inputs) => {
+        throw new Error("oopsie daisy");
+      },
+    },
+    actionTypes: {
+      createPost: PROTO_ACTION_TYPES.CREATE,
+    },
+    createContextAPI: () => {},
+  };
+
+  const rpcReq = createJSONRPCRequest("123", "createPost", { title: "a post" });
+
+  expect(await handleRequest(rpcReq, config)).toEqual({
+    id: "123",
+    jsonrpc: "2.0",
+    error: {
+      code: RuntimeErrors.UnknownError,
+      message: "oopsie daisy",
+    },
+  });
+});
+
+test("when a role based permission has already been granted by the main runtime", async () => {
+  const config = {
+    functions: {
+      createPost: async (ctx, inputs, api) => {
+        return {
+          title: inputs.title,
+        };
+      },
+    },
+    actionTypes: {
+      createPost: PROTO_ACTION_TYPES.CREATE,
+    },
+    createModelAPI: () => {},
+    createContextAPI: () => {},
+  };
+
+  let rpcReq = createJSONRPCRequest("123", "createPost", { title: "a post" });
+
+  Object.assign(rpcReq, {
+    ...rpcReq,
+    meta: { permissionState: { status: "granted", reason: "role" } },
+  });
+  expect(await handleRequest(rpcReq, config)).toEqual({
+    id: "123",
+    jsonrpc: "2.0",
+    result: {
+      title: "a post",
+    },
+    meta: {
+      headers: {},
+    },
+  });
+});
+
+test("when there is an unexpected object thrown in the custom function", async () => {
+  const config = {
+    functions: {
+      createPost: async (ctx, inputs) => {
+        throw { err: "oopsie daisy" };
+      },
+    },
+    actionTypes: {
+      createPost: PROTO_ACTION_TYPES.CREATE,
+    },
+    createContextAPI: () => {},
+  };
+
+  const rpcReq = createJSONRPCRequest("123", "createPost", { title: "a post" });
+
+  expect(await handleRequest(rpcReq, config)).toEqual({
+    id: "123",
+    jsonrpc: "2.0",
+    error: {
+      code: RuntimeErrors.UnknownError,
+      message: '{"err":"oopsie daisy"}',
+    },
+  });
+});
+
+// The following tests assert on the various
+// jsonrpc responses that *should* happen when a user
+// writes a custom function 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 ('adam', 'adam bull')
+    `.execute(db);
+
+    const models = {
+      post: new ModelAPI("post", undefined, {
+        post: {
+          author: {
+            relationshipType: "belongsTo",
+            foreignKey: "author_id",
+            referencesTable: "person",
+          },
+        },
+      }),
+    };
+
+    functionConfig = {
+      permissionFns: {},
+      actionTypes: {
+        createPost: PROTO_ACTION_TYPES.CREATE,
+        deletePost: PROTO_ACTION_TYPES.DELETE,
+      },
+      functions: {
+        createPost: async (ctx, inputs) => {
+          new Permissions().allow();
+
+          const post = await models.post.create({
+            id: KSUID.randomSync().string,
+            ...inputs,
+          });
+
+          return post;
+        },
+        deletePost: async (ctx, inputs) => {
+          new Permissions().allow();
+
+          const deleted = await models.post.delete(inputs);
+
+          return deleted;
+        },
+      },
+      createContextAPI: () => ({}),
+    };
+  });
+
+  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",
+    });
+
+    expect(await handleRequest(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 });
+
+    expect(await handleRequest(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', 'adam')
+    `.execute(db);
+
+    const rpcReq = createJSONRPCRequest("123", "createPost", {
+      title: "hello",
+      author_id: "something",
+    });
+
+    expect(await handleRequest(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" });
+
+    expect(await handleRequest(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 rpcReq2 = createJSONRPCRequest("123", "createPost", {
+      title: "123",
+      author_id: "fake",
+    });
+
+    expect(await handleRequest(rpcReq2, 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/index.d.ts

@@ -0,0 +1,86 @@
+export type IDWhereCondition = {
+  equals?: string | null;
+  oneOf?: string[] | null;
+};
+
+export type StringWhereCondition = {
+  startsWith?: string | null;
+  endsWith?: string | null;
+  oneOf?: string[] | null;
+  contains?: string | null;
+  notEquals?: string | null;
+  equals?: string | null;
+};
+
+export type BooleanWhereCondition = {
+  equals?: boolean | null;
+  notEquals?: boolean | null;
+};
+
+export type NumberWhereCondition = {
+  greaterThan?: number | null;
+  greaterThanOrEquals?: number | null;
+  lessThan?: number | null;
+  lessThanOrEquals?: number | null;
+  equals?: number | null;
+  notEquals?: number | null;
+};
+
+// Date database API
+export type DateWhereCondition = {
+  equals?: Date | string | null;
+  before?: Date | string | null;
+  onOrBefore?: Date | string | null;
+  after?: Date | string | null;
+  onOrAfter?: Date | string | null;
+};
+
+// Date query input
+export type DateQueryInput = {
+  equals?: string | null;
+  before?: string | null;
+  onOrBefore?: string | null;
+  after?: string | null;
+  onOrAfter?: string | null;
+};
+
+// Timestamp query input
+export type TimestampQueryInput = {
+  before: string | null;
+  after: string | null;
+};
+
+export type ContextAPI = {
+  headers: RequestHeaders;
+  response: Response;
+  isAuthenticated: boolean;
+  now(): Date;
+};
+
+export type Response = {
+  headers: Headers;
+};
+
+export type PageInfo = {
+  startCursor: string;
+  endCursor: string;
+  totalCount: number;
+  hasNextPage: boolean;
+  count: number;
+};
+
+// Request headers query API
+export type RequestHeaders = {
+  get(name: string): string;
+  has(name: string): boolean;
+};
+
+export declare class Permissions {
+  constructor();
+
+  // allow() can be used to explicitly permit access to an action
+  allow(): void;
+
+  // deny() can be used to explicitly deny access to an action
+  deny(): never;
+}

package/src/index.js

@@ -0,0 +1,27 @@
+const { ModelAPI } = require("./ModelAPI");
+const { RequestHeaders } = require("./RequestHeaders");
+const { handleRequest } = require("./handleRequest");
+const { handleJob } = require("./handleJob");
+const KSUID = require("ksuid");
+const { useDatabase } = require("./database");
+const {
+  Permissions,
+  PERMISSION_STATE,
+  checkBuiltInPermissions,
+} = require("./permissions");
+const tracing = require("./tracing");
+
+module.exports = {
+  ModelAPI,
+  RequestHeaders,
+  handleRequest,
+  handleJob,
+  useDatabase,
+  Permissions,
+  PERMISSION_STATE,
+  checkBuiltInPermissions,
+  tracing,
+  ksuid() {
+    return KSUID.randomSync().string;
+  },
+};

package/src/permissions.js

@@ -0,0 +1,78 @@
+const { AsyncLocalStorage } = require("async_hooks");
+
+class PermissionError extends Error {}
+
+const PERMISSION_STATE = {
+  UNKNOWN: "unknown",
+  PERMITTED: "permitted",
+  UNPERMITTED: "unpermitted",
+};
+
+// withPermissions sets the initial permission state from the go runtime in the AsyncLocalStorage so consumers further down the hierarchy can read or mutate the state
+// at will
+const withPermissions = async (initialValue, cb) => {
+  const permissions = new Permissions();
+
+  return await permissionsApiInstance.run({ permitted: initialValue }, () => {
+    return cb({ getPermissionState: permissions.getState });
+  });
+};
+
+const permissionsApiInstance = new AsyncLocalStorage();
+
+class Permissions {
+  // The Go runtime performs role based permission rule checks prior to calling the functions
+  // runtime, so the status could already be granted. If already granted, then we need to inherit that permission state as the state is later used to decide whether to run in process permission checks
+  // TLDR if a role based permission is relevant and it is granted, then it is effectively the same as the end user calling api.permissions.allow() explicitly in terms of behaviour.
+
+  allow() {
+    const store = (permissionsApiInstance.getStore().permitted = true);
+  }
+
+  deny() {
+    // if a user is explicitly calling deny() then we want to throw an error
+    // so that any further execution of the custom function stops abruptly
+    permissionsApiInstance.getStore().permitted = false;
+
+    throw new PermissionError();
+  }
+
+  getState() {
+    const permitted = permissionsApiInstance.getStore().permitted;
+
+    switch (true) {
+      case permitted === false:
+        return PERMISSION_STATE.UNPERMITTED;
+      case permitted === null:
+        return PERMISSION_STATE.UNKNOWN;
+      case permitted === true:
+        return PERMISSION_STATE.PERMITTED;
+    }
+  }
+}
+
+const checkBuiltInPermissions = async ({
+  rows,
+  permissionFns,
+  ctx,
+  db,
+  functionName,
+}) => {
+  for (const permissionFn of permissionFns) {
+    const result = await permissionFn(rows, ctx, db);
+    // if any of the permission functions return true,
+    // then we return early
+    if (result) {
+      return;
+    }
+  }
+
+  throw new PermissionError(`Not permitted to access ${functionName}`);
+};
+
+module.exports.checkBuiltInPermissions = checkBuiltInPermissions;
+module.exports.PermissionError = PermissionError;
+module.exports.PERMISSION_STATE = PERMISSION_STATE;
+module.exports.Permissions = Permissions;
+module.exports.withPermissions = withPermissions;
+module.exports.permissionsApiInstance = permissionsApiInstance;

package/src/permissions.test.js

@@ -0,0 +1,120 @@
+const {
+  permissionsApiInstance,
+  Permissions,
+  PERMISSION_STATE,
+  PermissionError,
+  checkBuiltInPermissions,
+} = require("./permissions");
+
+import { useDatabase } from "./database";
+
+import { beforeEach, describe, expect, test } from "vitest";
+
+let permissions;
+let ctx = {};
+let db = useDatabase();
+
+describe("explicit", () => {
+  beforeEach(() => {
+    permissions = new Permissions();
+  });
+
+  test("explicitly allowing execution", () => {
+    wrapWithAsyncLocalStorage({ permitted: null }, () => {
+      expect(permissions.getState()).toEqual(PERMISSION_STATE.UNKNOWN);
+
+      permissions.allow();
+
+      expect(permissions.getState()).toEqual(PERMISSION_STATE.PERMITTED);
+    });
+  });
+
+  test("explicitly denying execution", () => {
+    wrapWithAsyncLocalStorage({ permitted: null }, () => {
+      expect(permissions.getState()).toEqual(PERMISSION_STATE.UNKNOWN);
+
+      expect(() => permissions.deny()).toThrowError(PermissionError);
+
+      expect(permissions.getState()).toEqual(PERMISSION_STATE.UNPERMITTED);
+    });
+  });
+});
+
+describe("prior state", () => {
+  test("when the prior state is granted", () => {
+    wrapWithAsyncLocalStorage(
+      {
+        permitted: true,
+      },
+      () => {
+        expect(permissions.getState()).toEqual(PERMISSION_STATE.PERMITTED);
+      }
+    );
+  });
+});
+
+describe("check", () => {
+  const functionName = "createPerson";
+
+  test("check - success", async () => {
+    const permissionRule1 = (records, ctx, db) => {
+      // Only allow names starting with Adam
+      return records.every((r) => r.name.startsWith("Adam"));
+    };
+
+    const rows = [
+      {
+        id: "123",
+        name: "Adam Bull",
+      },
+      {
+        id: "234",
+        name: "Adam Lambert",
+      },
+    ];
+
+    await expect(
+      checkBuiltInPermissions({
+        rows,
+        ctx,
+        db,
+        functionName,
+        permissionFns: [permissionRule1],
+      })
+    ).resolves.ok;
+  });
+
+  test("check - failure", async () => {
+    // only allow Petes
+    const permissionRule1 = (records, ctx, db) => {
+      return records.every((r) => r.name === "Pete");
+    };
+
+    const rows = [
+      {
+        id: "123",
+        name: "Adam", // this one will cause an error to be thrown because Adam is not Pete
+      },
+      {
+        id: "234",
+        name: "Pete",
+      },
+    ];
+
+    await expect(
+      checkBuiltInPermissions({
+        rows,
+        ctx,
+        db,
+        functionName,
+        permissionFns: [permissionRule1],
+      })
+    ).rejects.toThrow();
+  });
+});
+
+function wrapWithAsyncLocalStorage(initialState, testFn) {
+  permissionsApiInstance.run(initialState, () => {
+    testFn();
+  });
+}