@occultist/occultist 0.0.1

package/lib/actions/context.ts

@@ -0,0 +1,170 @@
+import type {HandlerDefinition} from "../mod.js";
+import type {Registry} from "../registry.js";
+import type {ActionPayload, ActionSpec, ContextState, ParsedIRIValues} from "./spec.js";
+import type {ImplementedAction} from "./types.js";
+import type {ResponseBody} from "./writer.js";
+
+
+class EditableContext {
+  hit: boolean = false;
+  etag?: string;
+  status?: number;
+  body?: ResponseBody;
+};
+
+export type CacheContextArgs = {
+  req: Request;
+  url: string;
+  contentType: string;
+  public: boolean;
+  authKey?: string;
+  handler: HandlerDefinition;
+  params: ParsedIRIValues;
+  query: ParsedIRIValues;
+};
+
+
+/**
+ * Request context object.
+ */
+export class CacheContext {
+  #editable = new EditableContext();
+  req: Request;
+  method: string;
+  url: string;
+  contentType: string;
+  public: boolean = false
+  authKey?: string;
+  action: ImplementedAction;
+  registry: Registry;
+  params: ParsedIRIValues;
+  query: ParsedIRIValues;
+  headers: Headers = new Headers();
+
+  constructor(args: CacheContextArgs) {
+    this.req = args.req;
+    this.url = args.url;
+    this.contentType = args.contentType;
+    this.public = args.public;
+    this.authKey = args.authKey;
+    this.action = args.handler.action;
+    this.method = args.handler.action.method;
+    this.registry = args.handler.action.registry;
+    this.params = args.params;
+    this.query = args.query;
+
+    Object.freeze(this);
+  }
+
+  get hit(): boolean {
+    return this.#editable.hit;
+  }
+
+  set hit(hit: boolean) {
+    this.#editable.hit = hit;
+  }
+
+  get status(): undefined | number {
+    return this.#editable.status;
+  }
+
+  set status(status: number) {
+    this.#editable.status = status;
+  }
+
+  get body(): undefined | ResponseBody {
+    return this.#editable.body;
+  }
+
+  set body(body: ResponseBody) {
+    this.#editable.body = body;
+  }
+
+  get etag(): undefined | string {
+    return this.#editable.etag;
+  }
+
+  set etag(etag: string) {
+    this.#editable.etag = etag;
+  }
+
+  get [Symbol.toStringTag]() {
+    return `action=${this.action.name} method=${this.method} contentType=${this.contentType}`;
+  }
+}
+
+
+export type ContextArgs<
+  State extends ContextState = ContextState,
+  Spec extends ActionSpec = ActionSpec,
+> = {
+  req: Request;
+  url: string;
+  contentType: string;
+  public: boolean;
+  authKey?: string;
+  handler: HandlerDefinition<State, Spec>;
+  params: ParsedIRIValues;
+  query: ParsedIRIValues;
+  payload: ActionPayload<Spec>;
+};
+
+/**
+ * Request context object.
+ */
+export class Context<
+  State extends ContextState = ContextState,
+  Spec extends ActionSpec = ActionSpec,
+> {
+  #editable = new EditableContext();
+  req: Request;
+  method: string;
+  url: string;
+  contentType: string;
+  public: boolean = false
+  authKey?: string;
+  state: State = {} as State;
+  action: ImplementedAction<State, Spec>;
+  registry: Registry;
+  params: ParsedIRIValues;
+  query: ParsedIRIValues;
+  payload: ActionPayload<Spec>;
+  headers: Headers = new Headers();
+
+  constructor(args: ContextArgs<State, Spec>) {
+    this.req = args.req;
+    this.url = args.url;
+    this.contentType = args.contentType;
+    this.public = args.public;
+    this.authKey = args.authKey;
+    this.action = args.handler.action;
+    this.method = args.handler.action.method;
+    this.registry = args.handler.action.registry;
+    this.params = args.params;
+    this.query = args.query;
+    this.payload = args.payload;
+
+    Object.freeze(this);
+  }
+
+  get status(): undefined | number {
+    return this.#editable.status;
+  }
+
+  set status(status: number) {
+    this.#editable.status = status;
+  }
+
+  get body(): undefined | ResponseBody {
+    return this.#editable.body;
+  }
+
+  set body(body: ResponseBody) {
+    this.#editable.body = body;
+  }
+
+  get [Symbol.toStringTag]() {
+    return `action=${this.action.name} method=${this.method} contentType=${this.contentType}`;
+  }
+}
+

package/lib/actions/meta.ts

@@ -0,0 +1,251 @@
+import {CacheMiddleware} from '../cache/cache.js';
+import {CacheEntryDescriptor, CacheInstanceArgs} from '../cache/types.js';
+import {JSONValue} from '../jsonld.js';
+import {processAction} from '../processAction.js';
+import type {Registry} from '../registry.js';
+import type {Scope} from "../scopes.js";
+import {joinPaths} from '../utils/joinPaths.js';
+import {HandlerDefinition} from './actions.js';
+import {CacheContext, Context} from './context.js';
+import {Path} from "./path.js";
+import type {ActionSpec, ContextState, FileValue, NextFn, TransformerFn} from './spec.js';
+import type {HintArgs, ImplementedAction} from './types.js';
+import type {HTTPWriter, ResponseTypes} from "./writer.js";
+
+
+export const BeforeDefinition = 0;
+export const AfterDefinition = 1;
+
+const cacheMiddleware = new CacheMiddleware();
+
+export class ActionMeta<
+  State extends ContextState = ContextState,
+  Spec extends ActionSpec = ActionSpec,
+> {
+  rootIRI: string;
+  method: string;
+  name: string;
+  uriTemplate: string;
+  public: boolean = false;
+  authKey?: string;
+  path: Path;
+  hints: HintArgs[] = [];
+  transformers: Map<string, TransformerFn<JSONValue | FileValue, State, Spec>> = new Map();
+  scope?: Scope;
+  registry: Registry;
+  writer: HTTPWriter;
+  action?: ImplementedAction<State, Spec>;
+  acceptCache = new Set<string>();
+  compressBeforeCache: boolean = false;
+  cacheOccurance: 0 | 1 = BeforeDefinition;
+  cache: CacheInstanceArgs[] = [];
+  serverTiming: boolean = false;
+
+  constructor(
+    rootIRI: string,
+    method: string,
+    name: string,
+    uriTemplate: string,
+    registry: Registry,
+    writer: HTTPWriter,
+    scope?: Scope,
+  ) {
+    this.rootIRI = rootIRI;
+    this.method = method.toUpperCase()
+    this.name = name;
+    this.uriTemplate = joinPaths(rootIRI, uriTemplate);
+    this.registry = registry;
+    this.writer = writer;
+    this.scope = scope;
+    this.path = new Path(uriTemplate, rootIRI);
+  }
+
+  /**
+   * Called when the API is defined to compute all uncomputed values.
+   */
+  finalize() {
+    this.#setAcceptCache();
+  }
+
+  async handleRequest({
+    startTime,
+    contentType,
+    language: _language,
+    encoding: _encoding,
+    url,
+    req,
+    writer,
+    spec,
+    handler,
+  }: {
+    startTime: number;
+    contentType?: string;
+    language?: string;
+    encoding?: string;
+    url: string;
+    req: Request;
+    writer: HTTPWriter;
+    spec?: Spec;
+    handler?: HandlerDefinition<State, Spec>,
+  }): Promise<ResponseTypes> {
+    const state: State = {} as State;
+    const headers = new Headers();
+    let ctx: CacheContext | Context<State, Spec>;
+    let cacheCtx: CacheContext;
+    let prevTime = startTime;
+
+    const serverTiming = (name: string) => {
+      const nextTime = performance.now();
+      const duration = nextTime - prevTime;
+
+      headers.append('Server-Timing', `${name};dur=${duration.toPrecision(2)}`);
+      prevTime = nextTime;
+    }
+
+    if (this.serverTiming) serverTiming('enter');
+
+    // add auth check
+    if (this.hints.length !== 0) {
+      await Promise.all(
+        this.hints.map((hint) => writer.writeEarlyHints(hint))
+      );
+    }
+
+    let next: NextFn = async () => {
+      if (typeof handler.handler === 'function') {
+        await handler.handler(ctx as Context<State, Spec>);
+      } else {
+        ctx.status = 200;
+        ctx.body = handler.handler;
+      }
+
+      if (this.serverTiming) serverTiming('handle');
+    };
+
+    {
+      const upstream: NextFn = next;
+      next = async () => {
+        const res = await processAction<State, Spec>({
+          iri: url,
+          req,
+          spec: spec ?? {} as Spec,
+          state,
+          action: this.action,
+        });
+
+        ctx = new Context<State, Spec>({
+          req,
+          url,
+          contentType,
+          public: this.public,
+          handler,
+          params: res.params,
+          query: res.query,
+          payload: res.payload,
+        });
+
+        if (contentType != null) {
+          ctx.headers.set('Content-Type', contentType)
+        }
+
+        if (this.serverTiming) serverTiming('payload');
+
+        await upstream();
+      }
+    }
+
+    if (this.cache.length > 0) {
+      cacheCtx = new CacheContext({
+        req,
+        url,
+        contentType,
+        public: this.public,
+        handler,
+        params: {},
+        query: {},
+      });
+      const descriptors: CacheEntryDescriptor[] = this.cache.map(args => {
+        return {
+          contentType,
+          action: this.action as ImplementedAction,
+          request: req,
+          args,
+        };
+      });
+
+      const upstream = next;
+      next = async () => {
+        await cacheMiddleware.use(
+          descriptors,
+          cacheCtx,
+          async () => {
+            // cache was not hit if in this function
+            await upstream();
+
+            // the cache middleware requires these values are set 
+            cacheCtx.status = ctx.status;
+
+            if (ctx.body instanceof ReadableStream) {
+              const [a, b] = ctx.body.tee();
+              
+              ctx.body = a;
+              cacheCtx.body = b;
+            } else {
+              cacheCtx.body = ctx.body;
+            }
+        
+            for (const [key, value] of ctx.headers.entries()) {
+              cacheCtx.headers.set(key, value);
+            }
+          },
+        );
+      }
+    }
+
+    try {
+      await next();
+
+      if (cacheCtx?.hit) {
+        if (this.serverTiming) serverTiming('hit');
+        
+        // set the ctx so the writer has access to the cached values.
+        ctx = cacheCtx;
+      } else if (cacheCtx?.etag != null) {
+        ctx.headers.set('Etag', cacheCtx.etag);
+      }
+      
+      writer.mergeHeaders(headers);
+    } catch (err) {
+      writer.mergeHeaders(headers);
+
+      throw err;
+    }
+
+    writer.writeHead(ctx.status ?? 200, ctx.headers);
+
+    if (ctx.body != null) {
+      writer.writeBody(ctx.body);
+    }
+
+    return writer.response();
+  }
+
+  #setAcceptCache(): void {
+    const action = this.action;
+
+    if (action == null) {
+      return;
+    }
+
+    this.acceptCache.add('*/*');
+
+    for (const contentType of action.contentTypes) {
+      this.acceptCache.add(contentType);
+      this.acceptCache.add(contentType.replace(/[^/]+$/, '*'));
+    }
+  }
+
+  get [Symbol.toStringTag]() {
+    return `[Meta ${this.name} ${this.uriTemplate}]`;
+  }
+}

package/lib/actions/path.test.ts

@@ -0,0 +1,15 @@
+import test from 'node:test';
+import assert from "node:assert";
+import { Path } from "./path.js";
+
+
+test('URI template style path creates valid URL Pattern', () => {
+  const path = new Path(
+    '/api/recipes/{recipeUUID}/ingredients/{ingredientUUID}/units'
+      + '{?search,page,pageSize}'
+      + '{#sliceStart,sliceEnd}',
+    'https://example.com',
+  );
+
+  assert(path.pattern.test('https://example.com/api/recipes/xxxx-xxxx-xxxx-xxxx/ingredients/xxxx-xxxx-xxxx-xxxx/units'));
+});

package/lib/actions/path.ts

@@ -0,0 +1,99 @@
+import { makeURLPattern } from "../utils/makeURLPattern.js";
+
+const paramsRe = /((?<s>[^\{\}]+)|({(?<t>[\?\#])?(?<v>[^}]+)}))/g
+
+/**
+ * Util class for handling paths defined using URI templates.
+ * https://datatracker.ietf.org/doc/html/rfc6570.
+ *
+ * URI Templates are used instead of URLPattern format to conform to
+ * JSON-ld https://schema.org/entryPoint needs. It is possible to add
+ * regex syntax which would end up in the generated URLPattern making
+ * it in conflict with the URITemplate. To be fixed...
+ */
+export class Path {
+  #rootIRI: string;
+  #template: string;
+  #pattern: URLPattern;
+  #normalized: string;
+  #paramKeys: Set<string> = new Set();
+  #queryKeys: Set<string> = new Set();
+  #fragmentKeys: Set<string> = new Set();
+
+  constructor(template: string, rootIRI: string) {
+    this.#template = template;
+    this.#rootIRI = rootIRI;
+
+    [this.#pattern, this.#normalized] = this.#makePatterns()
+  }
+
+  get template(): string {
+    return this.#template;
+  }
+
+  get pattern(): URLPattern {
+    return this.#pattern;
+  }
+
+  get normalized(): string {
+    return this.#normalized;
+  }
+
+  /**
+   * Returns the location of the given key if it is present in
+   * the path.
+   */
+  locationOf(key: string): 'params' | 'query' | 'fragment' | null {
+    if (this.#paramKeys.has(key)) {
+      return 'params';
+    } else if (this.#queryKeys.has(key)) {
+      return 'query';
+    } else if (this.#fragmentKeys.has(key)) {
+      return 'fragment';
+    }
+
+    return null;
+  }
+
+  #makePatterns(): [URLPattern, string] {
+    const paramsRe = /((?<s>[^\{\}]+)|({(?<t>[\?\#])?(?<v>[^}]+)}))/g
+    let pattern: string = '';
+    let normalized: string = '';
+    
+    // assign values to key location sets for quick querying
+    let match: RegExpExecArray | null;
+    let foundQueryOrFragment = false;
+    let index = 0;
+
+    while ((match = paramsRe.exec(this.#template))) {
+      const segment = match.groups?.s;
+      const type = match.groups?.t;
+      const value = match.groups?.v;
+
+      if (type != null) {
+        foundQueryOrFragment = true;
+      }
+
+      if (!foundQueryOrFragment && segment != null && type == null) {
+        normalized += segment;
+        pattern += segment;
+      }
+      
+      if (value == null) {
+        continue;
+      }
+
+      if (!foundQueryOrFragment && value != null) {
+        index++;
+        pattern += `:${value}`;
+        normalized += `:value${index}`;
+      }
+    }
+
+    return [
+      makeURLPattern(pattern, this.#rootIRI),
+      normalized,
+    ];
+  }
+  
+}