@occultist/occultist 0.0.4 → 0.0.6

package/lib/actions/context.ts

@@ -1,8 +1,8 @@
-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";
+import type {HandlerDefinition} from "../mod.ts";
+import type {Registry} from "../registry.ts";
+import type {ActionPayload, ActionSpec, ContextState, ParsedIRIValues} from "./spec.ts";
+import type {AuthState, ImplementedAction} from "./types.ts";
+import type {ResponseBody} from "./writer.ts";
 
 
 class EditableContext {
@@ -12,22 +12,26 @@ class EditableContext {
   body?: ResponseBody;
 };
 
-export type CacheContextArgs = {
+export type CacheContextArgs<
+  Auth extends AuthState = AuthState,
+> = {
   req: Request;
   url: string;
   contentType: string;
   public: boolean;
   authKey?: string;
+  auth: Auth;
   handler: HandlerDefinition;
   params: ParsedIRIValues;
   query: ParsedIRIValues;
 };
 
-
 /**
  * Request context object.
  */
-export class CacheContext {
+export class CacheContext<
+  Auth extends AuthState = AuthState,
+> {
   #editable = new EditableContext();
   req: Request;
   method: string;
@@ -35,18 +39,20 @@ export class CacheContext {
   contentType: string;
   public: boolean = false
   authKey?: string;
+  auth: Auth;
   action: ImplementedAction;
   registry: Registry;
   params: ParsedIRIValues;
   query: ParsedIRIValues;
   headers: Headers = new Headers();
 
-  constructor(args: CacheContextArgs) {
+  constructor(args: CacheContextArgs<Auth>) {
     this.req = args.req;
     this.url = args.url;
     this.contentType = args.contentType;
     this.public = args.public;
     this.authKey = args.authKey;
+    this.auth = args.auth;
     this.action = args.handler.action;
     this.method = args.handler.action.method;
     this.registry = args.handler.action.registry;
@@ -96,6 +102,7 @@ export class CacheContext {
 
 export type ContextArgs<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec,
 > = {
   req: Request;
@@ -103,6 +110,7 @@ export type ContextArgs<
   contentType: string;
   public: boolean;
   authKey?: string;
+  auth: Auth;
   handler: HandlerDefinition<State, Spec>;
   params: ParsedIRIValues;
   query: ParsedIRIValues;
@@ -114,6 +122,7 @@ export type ContextArgs<
  */
 export class Context<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec,
 > {
   #editable = new EditableContext();
@@ -123,6 +132,7 @@ export class Context<
   contentType: string;
   public: boolean = false
   authKey?: string;
+  auth: Auth;
   state: State = {} as State;
   action: ImplementedAction<State, Spec>;
   registry: Registry;
@@ -131,12 +141,13 @@ export class Context<
   payload: ActionPayload<Spec>;
   headers: Headers = new Headers();
 
-  constructor(args: ContextArgs<State, Spec>) {
+  constructor(args: ContextArgs<State, Auth, Spec>) {
     this.req = args.req;
     this.url = args.url;
     this.contentType = args.contentType;
     this.public = args.public;
     this.authKey = args.authKey;
+    this.auth = args.auth;
     this.action = args.handler.action;
     this.method = args.handler.action.method;
     this.registry = args.handler.action.registry;
@@ -145,6 +156,7 @@ export class Context<
     this.payload = args.payload;
 
     Object.freeze(this);
+    Object.freeze(this.auth);
   }
 
   get status(): undefined | number {

package/lib/actions/meta.ts

@@ -1,16 +1,20 @@
-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";
+import {Accept} from '../accept.ts';
+import {CacheMiddleware} from '../cache/cache.ts';
+import type {CacheEntryDescriptor, CacheInstanceArgs, CacheSemantics} from '../cache/types.ts';
+import {ProblemDetailsError} from '../errors.ts';
+import type {JSONValue} from '../jsonld.ts';
+import {processAction, type ProcessActionResult} from '../processAction.ts';
+import type {Registry} from '../registry.ts';
+import {WrappedRequest} from '../request.ts';
+import type {Scope} from "../scopes.ts";
+import {joinPaths} from '../utils/joinPaths.ts';
+import {HandlerDefinition} from './actions.ts';
+import {ActionSet} from './actionSets.ts';
+import {CacheContext, Context} from './context.ts';
+import {Path} from "./path.ts";
+import type {ActionSpec, ContextState, FileValue, NextFn, TransformerFn} from './spec.ts';
+import type {AuthMiddleware, AuthState, CacheHitHeader, HintArgs, ImplementedAction} from './types.ts';
+import {ResponseWriter, type HTTPWriter, type ResponseTypes} from "./writer.ts";
 
 
 export const BeforeDefinition = 0;
@@ -20,6 +24,7 @@ const cacheMiddleware = new CacheMiddleware();
 
 export class ActionMeta<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec,
 > {
   rootIRI: string;
@@ -38,6 +43,7 @@ export class ActionMeta<
   acceptCache = new Set<string>();
   compressBeforeCache: boolean = false;
   cacheOccurance: 0 | 1 = BeforeDefinition;
+  auth?: AuthMiddleware<Auth>;
   cache: CacheInstanceArgs[] = [];
   serverTiming: boolean = false;
 
@@ -67,18 +73,44 @@ export class ActionMeta<
     this.#setAcceptCache();
   }
 
+  async perform(req: Request): Promise<Response> {
+    const actionSet = new ActionSet(this.rootIRI, this.method, this.path.normalized, [this]);
+    const wrapped = new WrappedRequest(this.rootIRI, req);
+    const writer = new ResponseWriter();
+    const accept = Accept.from(req);
+    const url = new URL(wrapped.url);
+    const result = actionSet.matches(wrapped.method, url.pathname, accept);
+
+    if (result.type === 'match') {
+      const handler = this.action.handlerFor(result.contentType);
+
+      return this.handleRequest({
+        startTime: performance.now(),
+        contentType: result.contentType,
+        url: url.toString(),
+        req: wrapped,
+        writer,
+        spec: this.action.spec as Spec,
+        handler,
+      }) as Promise<Response>;
+    }
+    
+    return new Response(null, { status: 404 });
+  }
+
+  /**
+   *
+   */
   async handleRequest({
-    startTime,
     contentType,
-    language: _language,
-    encoding: _encoding,
     url,
     req,
     writer,
     spec,
     handler,
+    cacheHitHeader,
+    startTime,
   }: {
-    startTime: number;
     contentType?: string;
     language?: string;
     encoding?: string;
@@ -87,22 +119,28 @@ export class ActionMeta<
     writer: HTTPWriter;
     spec?: Spec;
     handler?: HandlerDefinition<State, Spec>,
+    cacheHitHeader?: CacheHitHeader;
+    startTime?: number;
   }): Promise<ResponseTypes> {
     const state: State = {} as State;
     const headers = new Headers();
-    let ctx: CacheContext | Context<State, Spec>;
-    let cacheCtx: CacheContext;
+
+    let authKey: string | undefined;
+    let auth: Auth = {} as Auth;
+    let ctx: CacheContext<Auth> | Context<State, Auth, Spec>;
+    let cacheCtx: CacheContext<Auth>;
     let prevTime = startTime;
+    let performServerTiming = this.serverTiming && startTime != null;
 
     const serverTiming = (name: string) => {
       const nextTime = performance.now();
       const duration = nextTime - prevTime;
 
-      headers.append('Server-Timing', `${name};dur=${duration.toPrecision(2)}`);
+      headers.append('Server-Timing', `${name};dur=${duration.toFixed(2)}`);
       prevTime = nextTime;
     }
 
-    if (this.serverTiming) serverTiming('enter');
+    if (performServerTiming) serverTiming('enter');
 
     // add auth check
     if (this.hints.length !== 0) {
@@ -113,72 +151,86 @@ export class ActionMeta<
 
     let next: NextFn = async () => {
       if (typeof handler.handler === 'function') {
-        await handler.handler(ctx as Context<State, Spec>);
+        await handler.handler(ctx as Context<State, Auth, Spec>);
       } else {
         ctx.status = 200;
         ctx.body = handler.handler;
       }
 
-      if (this.serverTiming) serverTiming('handle');
+      if (performServerTiming) 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,
-        });
+        let processed: ProcessActionResult<Spec>;
+
+        if (spec != null) {
+          processed = await processAction<State, Spec>({
+            iri: url,
+            req,
+            spec: spec ?? {} as Spec,
+            state,
+            action: this.action,
+          });
+        }
 
-        ctx = new Context<State, Spec>({
+        ctx = new Context<State, Auth, Spec>({
           req,
           url,
           contentType,
-          public: this.public,
+          public: this.public && authKey == null,
+          auth,
+          authKey,
           handler,
-          params: res.params,
-          query: res.query,
-          payload: res.payload,
+          params: processed.params ?? {},
+          query: processed.query ?? {},
+          payload: processed.payload ?? {} as ProcessActionResult<Spec>['payload'],
         });
 
         if (contentType != null) {
           ctx.headers.set('Content-Type', contentType)
         }
 
-        if (this.serverTiming) serverTiming('payload');
+        if (performServerTiming) 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 () => {
+        cacheCtx = new CacheContext({
+          req,
+          url,
+          contentType,
+          public: this.public && authKey == null,
+          auth,
+          authKey,
+          handler,
+          params: {},
+          query: {},
+        });
+        const descriptors: CacheEntryDescriptor[] = this.cache.map(args => {
+          return {
+            contentType,
+            semantics: args.semantics ?? req.method.toLowerCase() as CacheSemantics,
+            action: this.action as ImplementedAction,
+            request: req,
+            args,
+          };
+        });
+
         await cacheMiddleware.use(
           descriptors,
           cacheCtx,
           async () => {
+            // write any cache headers to the response headers.
+            // this should be reviewed as it may be unsafe to
+            // allow a handler to override these headers.
+            writer.mergeHeaders(cacheCtx.headers);
+
             // cache was not hit if in this function
             await upstream();
 
@@ -202,11 +254,44 @@ export class ActionMeta<
       }
     }
 
+    if (this.auth != null) {
+      const upstream = next;
+      next = async () => {
+        const res = await this.auth(req);
+
+        if (Array.isArray(res) &&
+            typeof res[0] === 'string' &&
+            res.length > 0) {
+          authKey = res[0];
+          auth = res[1];
+
+          await upstream();
+        } else if (this.public) {
+          await upstream();
+        } else {
+  
+          // Failed authentication on a private endpoint.
+          throw new ProblemDetailsError(404, {
+            title: 'Not found',
+          });
+        }
+      };
+    }
+
+
     try {
       await next();
 
       if (cacheCtx?.hit) {
-        if (this.serverTiming) serverTiming('hit');
+        if (performServerTiming) serverTiming('hit');
+
+        if (Array.isArray(cacheHitHeader)) {
+          cacheCtx.headers.set(cacheHitHeader[0], cacheHitHeader[1]);
+        } else if (typeof cacheHitHeader === 'string') {
+          cacheCtx.headers.set(cacheHitHeader, 'HIT');
+        } else if (cacheHitHeader) {
+          cacheCtx.headers.set('X-Cache', 'HIT');
+        }
         
         // set the ctx so the writer has access to the cached values.
         ctx = cacheCtx;

package/lib/actions/path.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from "node:assert";
-import { Path } from "./path.js";
+import { Path } from "./path.ts";
 
 
 test('URI template style path creates valid URL Pattern', () => {

package/lib/actions/path.ts

@@ -1,4 +1,4 @@
-import { makeURLPattern } from "../utils/makeURLPattern.js";
+import { makeURLPattern } from "../utils/makeURLPattern.ts";
 
 const paramsRe = /((?<s>[^\{\}]+)|({(?<t>[\?\#])?(?<v>[^}]+)}))/g
 

package/lib/actions/spec.ts

@@ -1,6 +1,6 @@
-import type { JSONPrimitive, JSONValue, OrArray, RecursiveDigit, RecursiveIncrement, TypeDef } from "../jsonld.js";
-import {Action} from "./actions.js";
-import type { Context } from './context.js';
+import type { JSONPrimitive, JSONValue, OrArray, RecursiveDigit, RecursiveIncrement, TypeDef } from "../jsonld.ts";
+import {Action} from "./actions.ts";
+import type { Context } from './context.ts';
 
 export type EmptyState = Record<string, unknown>;
 export type EmptySpec = Map<PropertyKey, never>;

package/lib/actions/types.ts

@@ -1,11 +1,40 @@
-import type { HTTPWriter } from "./writer.js";
-import type { Registry } from '../registry.js';
-import type { Scope } from "../scopes.js";
-import type { ContextState, ActionSpec } from "./spec.js";
-import type { Context } from "./context.js";
+import type { HTTPWriter } from "./writer.ts";
+import type { Registry } from '../registry.ts';
+import type { Scope } from "../scopes.ts";
+import type { ContextState, ActionSpec } from "./spec.ts";
+import type { Context } from "./context.ts";
 import type { ServerResponse } from "node:http";
-import type { JSONObject, TypeDef } from "../jsonld.js";
-import type {HandlerDefinition} from "../mod.js";
+import type { JSONObject, TypeDef } from "../jsonld.ts";
+import type {HandlerDefinition} from "../mod.ts";
+
+export type CacheHitHeader = boolean | string | [header: string, value: string];
+
+export type AuthState = Record<string, unknown>;
+
+/**
+ * Middleware that identifies the authenticating agent from the request
+ * and confirms they have access to the resource.
+ * 
+ * When successfully authenticated the middleware should return with
+ * an array of two values. The first being a key unique to the user, or
+ * group, which can access this resource. This key is used for varying
+ * private cache so should alway vary on the user if personalized information
+ * would be returned in the response.
+ *
+ * The second response item is optional and should be an object holding identifying
+ * information such as permissions or details of the user or group that might be used
+ * when forming the response.
+ *
+ * @param req The request.
+ */
+export type AuthMiddleware<
+  Auth extends AuthState = AuthState,
+> =  (req: Request) => 
+  | void
+  | Promise<void>
+  | [authKey: string, auth?: Auth]
+  | Promise<[authKey: string, auth?: Auth]>
+;
 
 export type HintLink = {
   href: string;
@@ -57,8 +86,9 @@ export type HandlerValue = Exclude<BodyInit, ReadableStream>;
  */
 export type HandlerFn<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec,
-> = (ctx: Context<State, Spec>) => void | Promise<void>;
+> = (ctx: Context<State, Auth, Spec>) => void | Promise<void>;
 
 /**
  * A handler object argument.
@@ -68,10 +98,11 @@ export type HandlerFn<
  */
 export interface HandlerObj<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec,
 > {
   contentType: string | string[];
-  handler: HandlerFn<State, Spec> | HandlerValue;
+  handler: HandlerFn<State, Auth, Spec> | HandlerValue;
   meta?: HandlerMeta;
   hints?: HintArgs;
 };
@@ -81,25 +112,28 @@ export interface HandlerObj<
  */
 export type HandlerArgs<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec,
 > =
   | HandlerValue
-  | HandlerFn<State, Spec>
-  | HandlerObj<State, Spec>
+  | HandlerFn<State, Auth, Spec>
+  | HandlerObj<State, Auth, Spec>
 ;
 
 export type HandleRequestArgs = {
-  startTime: number;
   contentType?: string;
   language?: string;
   encoding?: string;
   url: string;
   req: Request;
   writer: HTTPWriter;
+  startTime?: number;
+  cacheHitHeader?: CacheHitHeader;
 };
 
 export interface ImplementedAction<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec,
 > {
   readonly public: boolean;
@@ -113,16 +147,27 @@ export interface ImplementedAction<
   readonly spec: Spec;
   readonly registry: Registry;
   readonly scope?: Scope;
-  readonly handlers: HandlerDefinition<State, Spec>[];
+  readonly handlers: HandlerDefinition<State, Auth, Spec>[];
   readonly contentTypes: string[];
   readonly context: JSONObject;
 
   /**
-   * @todo
-   *
    * Creates a URL compatible with this action.
    */
   url(): string;
+    
+  /**
+   * Retrives the handler configured for the given content type.
+   *
+   * @param contentType   The content type.
+   */
+  handlerFor(contentType: string): HandlerDefinition<State, Auth, Spec> | undefined;
+
+  /**
+   * Performs this action using the given fetch Request
+   * returning a Response.
+   */
+  perform(req: Request): Promise<Response>;
 
   /**
    * @todo

package/lib/actions/writer.test.ts

@@ -1,7 +1,7 @@
 import {createServer} from 'node:http';
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import {ResponseWriter} from './writer.js';
+import {ResponseWriter} from './writer.ts';
 import {AddressInfo} from 'node:net';
 
 
@@ -20,7 +20,7 @@ test('Writer writes hints', () => {
             fetchPriority: 'high',
           },
           {
-            href: 'https://example.com/main.js',
+            href: 'https://example.com/main.ts',
             as: 'script',
             preload: true,
             fetchPriority: 'low',

package/lib/actions/writer.ts

@@ -1,5 +1,5 @@
 import { ServerResponse } from 'node:http';
-import type { HintLink, HintArgs, HintObj } from './types.js';
+import type { HintLink, HintArgs, HintObj } from './types.ts';
 
 
 function isHintLink(hint: HintObj | HintLink): hint is HintLink {