added support for ports, baseUrl and ctx object

Signed-off-by: Noorain Panjwani <[email protected]>

Author: YourTechBud

README.md

@@ -1,2 +1,33 @@
-# space-api-ts
+# Space SDK (Typescript)
 Typescript API for Space Cloud
+
+## Worker API
+
+Sample usage
+```ts
+import { Server } from "@spacecloud-io/worker";
+import { z } from "zod";
+
+// We first create the server object
+const server = Server.create({ 
+  name: "myServer",
+  baseUrl: "/v2",     // Optional. Defaults to `/v1`.
+  port: 8080          // Optional. Defaults to `3000`.
+});
+
+// Create a router object. All operations are registered on this router.
+const router = server.router();
+
+// Register a query object.
+router.query("operate")                       // `opId` is the name of the operation
+  .method("GET")                              // Defaults to `GET` for queries and `POST` for mutations
+  .url("/v1/operate")                         // Defaults to `${baseURL}/${opId}`                                                 
+  .input(z.object({ name: z.string() }))
+  .output(z.object({ greeting: z.string() }))
+  .fn(async (_ctx, req) => {
+    return { greeting: `Hi ${req.name}` };
+  });
+
+// Start the express http server.
+server.start();
+```

apps/basic/src/index.ts

@@ -2,13 +2,13 @@ import { Server } from "@spacecloud-io/worker";
 import { z } from "zod";
 import * as schemas from "./schema";
 
-const server = Server.create("myServer");
+const server = Server.create({ name: "myServer" });
 const router = server.router();
 
-router.mutation("operate")
-  .input(z.object({ name: z.string()}))
+router.query("operate")
+  .input(z.object({ name: z.string() }))
   .output(z.object({ greeting: z.string() }))
-  .fn(async (req) => {
+  .fn(async (_ctx, req) => {
     return { greeting: `Hi ${req.name}` };
   });
 
@@ -17,7 +17,7 @@ router.mutation("operate")
 router.mutation("addTodo")
   .input(schemas.addTodoRequestSchema)
   .output(schemas.addTodoResponseSchema)
-  .fn(async (req) => {
+  .fn(async (_ctx, req) => {
     console.log("Adding todo:", req);
     return { id: "myid" };
   });

packages/worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacecloud-io/worker",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,16 +10,16 @@
     "lint": "eslint ./"
   },
   "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "author": "Noorain Panjwani <[email protected]>",
+  "license": "Apache-2.0",
   "dependencies": {
     "express": "^4.18.2",
     "openapi3-ts": "^4.1.2",
-    "tsconfig": "workspace:^",
     "zod": "^3.21.4",
     "zod-to-json-schema": "^3.21.1"
   },
   "devDependencies": {
-    "@types/express": "^4.17.17"
+    "@types/express": "^4.17.17",
+    "tsconfig": "workspace:^"
   }
 }

packages/worker/src/context.ts

@@ -0,0 +1,33 @@
+import { Request, Response } from "express";
+import { extractHeadersFromRequest } from "./helpers";
+
+export class Context {
+  private req: Request;
+  private res: Response;
+
+  public metadata: { [key: string]: string };
+  
+  constructor(req: Request, res: Response) {
+    this.req = req;
+    this.res = res;
+    this.metadata = extractHeadersFromRequest(req);
+  }
+
+/**
+ * Returns the request object provided by express. Helpful for accessing
+ * underlying request properties like hostname & cookies. For headers, use metadata.
+ * @returns 
+ */
+  public getRawRequestObject(): Request {
+    return this.req;
+  }
+
+/**
+ * Returns the response object provided by express. Useful for setting properties in response
+ * object like headers.
+ * @returns 
+ */
+  public getRawResponseObject(): Response {
+    return this.res;
+  }
+}

packages/worker/src/helpers.ts

@@ -1,3 +1,4 @@
+import { Request } from "express";
 import openapi3 from "openapi3-ts/oas30";
 
 export const getPayloadFromParams = (query: any, inputSchema: any) => {
@@ -71,3 +72,13 @@ export const getErrorResponseSchema = () => {
 
   return responseObject;
 };
+
+export const extractHeadersFromRequest = (req: Request) => {
+  const headers: { [key: string]: string } = {};
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (typeof value === "string") headers[key] = value;
+    else if (Array.isArray(value)) headers[key] = value[0];
+  }
+
+  return headers;
+};

packages/worker/src/route.ts

@@ -4,14 +4,15 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 import openapi3 from "openapi3-ts/oas30";
 
 import { getErrorResponseSchema, getPayloadFromParams, isZodTypeNull, processException } from "./helpers";
+import { Context } from "./context";
 
 export type RouteUpdater = (r: Route<any, any>) => void;
 
 export interface RouteConfig {
   opId: string;
   opType: string;
   method: string;
-  url?: string;
+  url: string;
   jsonSchema: {
     input: any;
     output: any;
@@ -27,7 +28,7 @@ export interface ZodSchemas {
   output?: z.ZodType;
 }
 
-export type Query<I, O> = (input: I) => Promise<O>;
+export type Query<I, O> = (ctx: Context, input: I) => Promise<O>;
 
 export class Route<I, O> {
   private config: RouteConfig;
@@ -39,23 +40,36 @@ export class Route<I, O> {
   constructor(config: RouteConfig, updater: RouteUpdater) {
     this.config = config;
     this.updater = updater;
-
-    // Autogenerate a url if it wasn't already provided by the user
-    if (this.config.url === undefined) {
-      this.config.url = `/v1/${this.config.opId}`;
-    }
   }
 
+  /**
+   * Method configures the HTTP method to use for this operation 
+   * @param method 
+   * @returns 
+   */
   public method(method: string) {
     this.config.method = method;
     return this;
   }
 
+  /**
+   * Url configures the URL to use for this operation
+   * @param url 
+   * @returns 
+   */
   public url(url: string) {
     this.config.url = url;
     return this;
   }
 
+  /**
+   * Input configures the data type of the request object to pass in the handler function
+   * registered by the user. It also performs a JSONSchema check before calling the handler function.
+   * The proeprties specified by the input may be accepted via the body or as query parameters based
+   * on the method being used for the operation
+   * @param schema ZOD schema object
+   * @returns 
+   */
   public input<T>(schema: z.ZodType<T>) {
     // Create json schema from zod schema
     this.config.zodSchemas.input = schema;
@@ -71,6 +85,13 @@ export class Route<I, O> {
     return r;
   }
 
+  /**
+   * Output configures the data type of the response object to that the handler function registered
+   * by the user will return.
+   * The returned object will always be sent as a JSON payload in the response body.
+   * @param schema ZOD schema object
+   * @returns 
+   */
   public output<T>(schema: z.ZodType<T>) {
     // Create json schema from zod schema
     this.config.zodSchemas.output = schema;
@@ -86,12 +107,17 @@ export class Route<I, O> {
     return r;
   }
 
-  public fn(query: Query<I, O>) {
-    this.handler = query;
+  /**
+   * fn accepts the procedure that needs to be called when this operation is invoked
+   * @param handlerFn 
+   * @returns
+   */
+  public fn(handlerFn: Query<I, O>) {
+    this.handler = handlerFn;
     return this;
   }
 
-  public getOpenAPIOperation() {
+  public _getOpenAPIOperation() {
     // Process request schema
     const isRequestNull = isZodTypeNull(this.config.zodSchemas.input);
     const requestBodyObject: openapi3.RequestBodyObject = {
@@ -131,12 +157,6 @@ export class Route<I, O> {
       ["x-request-op-type"]: this.config.opType,
     };
 
-    // Unnecessary check to remove linting error. We don't really require this
-    // since we are already performing this step in the constructor. 
-    if (!this.config.url) {
-      this.config.url = `/v1/${this.config.opId}`;
-    }
-
     return {
       path: this.config.url,
       method: this.config.method,
@@ -173,20 +193,15 @@ export class Route<I, O> {
 
       // Simply return back the response
       try {
-        const output = await this.handler(payload);
+        const ctx = new Context(req, res);
+        const output = await this.handler(ctx, payload);
         res.json(output);
       } catch (e: any) {
         // Return status code 500 if we catch an exception
         res.status(500).json({ message: processException(e) });
       }
     };
 
-    // Unnecessary check to remove linting error. We don't really require this
-    // since we are already performing this step in the constructor. 
-    if (!this.config.url) {
-      this.config.url = `/v1/${this.config.opId}`;
-    }
-
     // Register the handler for the appropriate method
     switch (this.config.method) {
       case "get":