@occultist/occultist 0.0.4 → 0.0.6

package/dist/actions/meta.js

@@ -1,8 +1,13 @@
-import { CacheMiddleware } from '../cache/cache.js';
-import { processAction } from '../processAction.js';
-import { joinPaths } from '../utils/joinPaths.js';
-import { CacheContext, Context } from './context.js';
+import { Accept } from "../accept.js";
+import { CacheMiddleware } from "../cache/cache.js";
+import { ProblemDetailsError } from "../errors.js";
+import { processAction } from "../processAction.js";
+import { WrappedRequest } from "../request.js";
+import { joinPaths } from "../utils/joinPaths.js";
+import { ActionSet } from "./actionSets.js";
+import { CacheContext, Context } from "./context.js";
 import { Path } from "./path.js";
+import { ResponseWriter } from "./writer.js";
 export const BeforeDefinition = 0;
 export const AfterDefinition = 1;
 const cacheMiddleware = new CacheMiddleware();
@@ -23,6 +28,7 @@ export class ActionMeta {
     acceptCache = new Set();
     compressBeforeCache = false;
     cacheOccurance = BeforeDefinition;
+    auth;
     cache = [];
     serverTiming = false;
     constructor(rootIRI, method, name, uriTemplate, registry, writer, scope) {
@@ -41,19 +47,46 @@ export class ActionMeta {
     finalize() {
         this.#setAcceptCache();
     }
-    async handleRequest({ startTime, contentType, language: _language, encoding: _encoding, url, req, writer, spec, handler, }) {
+    async perform(req) {
+        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,
+                handler,
+            });
+        }
+        return new Response(null, { status: 404 });
+    }
+    /**
+     *
+     */
+    async handleRequest({ contentType, url, req, writer, spec, handler, cacheHitHeader, startTime, }) {
         const state = {};
         const headers = new Headers();
+        let authKey;
+        let auth = {};
         let ctx;
         let cacheCtx;
         let prevTime = startTime;
+        let performServerTiming = this.serverTiming && startTime != null;
         const serverTiming = (name) => {
             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)
+        if (performServerTiming)
             serverTiming('enter');
         // add auth check
         if (this.hints.length !== 0) {
@@ -67,58 +100,70 @@ export class ActionMeta {
                 ctx.status = 200;
                 ctx.body = handler.handler;
             }
-            if (this.serverTiming)
+            if (performServerTiming)
                 serverTiming('handle');
         };
         {
             const upstream = next;
             next = async () => {
-                const res = await processAction({
-                    iri: url,
-                    req,
-                    spec: spec ?? {},
-                    state,
-                    action: this.action,
-                });
+                let processed;
+                if (spec != null) {
+                    processed = await processAction({
+                        iri: url,
+                        req,
+                        spec: spec ?? {},
+                        state,
+                        action: this.action,
+                    });
+                }
                 ctx = new Context({
                     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 ?? {},
                 });
                 if (contentType != null) {
                     ctx.headers.set('Content-Type', contentType);
                 }
-                if (this.serverTiming)
+                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 = this.cache.map(args => {
-                return {
-                    contentType,
-                    action: this.action,
-                    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 = this.cache.map(args => {
+                    return {
+                        contentType,
+                        semantics: args.semantics ?? req.method.toLowerCase(),
+                        action: this.action,
+                        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();
                     // the cache middleware requires these values are set 
@@ -137,11 +182,42 @@ 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)
+                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/dist/actions/spec.d.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>;
 export type ContextState = Record<string, unknown>;

package/dist/actions/types.d.ts

@@ -1,11 +1,30 @@
-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;
     rel?: string | string[];
@@ -43,33 +62,34 @@ export type HandlerValue = Exclude<BodyInit, ReadableStream>;
  * An action handler function that is passed a context object.
  * Responses should be set on the context object.
  */
-export type HandlerFn<State extends ContextState = ContextState, Spec extends ActionSpec = ActionSpec> = (ctx: Context<State, Spec>) => void | Promise<void>;
+export type HandlerFn<State extends ContextState = ContextState, Auth extends AuthState = AuthState, Spec extends ActionSpec = ActionSpec> = (ctx: Context<State, Auth, Spec>) => void | Promise<void>;
 /**
  * A handler object argument.
  *
  * Occultist extensions can use this handler argument method to provide arguments
  * which are usually defined while defining the action.
  */
-export interface HandlerObj<State extends ContextState = ContextState, Spec extends ActionSpec = ActionSpec> {
+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;
 }
 /**
  * Handler arguments for an action.
  */
-export type HandlerArgs<State extends ContextState = ContextState, Spec extends ActionSpec = ActionSpec> = HandlerValue | HandlerFn<State, Spec> | HandlerObj<State, Spec>;
+export type HandlerArgs<State extends ContextState = ContextState, Auth extends AuthState = AuthState, Spec extends ActionSpec = ActionSpec> = HandlerValue | 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, Spec extends ActionSpec = ActionSpec> {
+export interface ImplementedAction<State extends ContextState = ContextState, Auth extends AuthState = AuthState, Spec extends ActionSpec = ActionSpec> {
     readonly public: boolean;
     readonly method: string;
     readonly term?: string;
@@ -81,15 +101,24 @@ export interface ImplementedAction<State extends ContextState = ContextState, Sp
     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/dist/actions/writer.d.ts

@@ -1,5 +1,5 @@
 import { ServerResponse } from 'node:http';
-import type { HintArgs } from './types.js';
+import type { HintArgs } from './types.ts';
 export type ResponseTypes = ServerResponse | Response;
 export type ResponseBody = BodyInit;
 export interface HTTPWriter {

package/dist/actions/writer.test.js

@@ -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.js";
 test('Writer writes hints', () => {
     return new Promise((resolve, reject) => {
         const server = createServer();
@@ -16,7 +16,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/dist/cache/cache.d.ts

@@ -1,5 +1,5 @@
-import { CacheContext, NextFn, Registry } from '../mod.js';
-import type { CacheBuilder, CacheEntryDescriptor, CacheETagArgs, CacheETagInstanceArgs, CacheHTTPArgs, CacheHTTPInstanceArgs, CacheMeta, CacheStorage, CacheStoreArgs, CacheStoreInstanceArgs, UpstreamCache } from './types.js';
+import { CacheContext, type NextFn, Registry } from '../mod.ts';
+import type { CacheBuilder, CacheEntryDescriptor, CacheETagArgs, CacheETagInstanceArgs, CacheHTTPArgs, CacheHTTPInstanceArgs, CacheMeta, CacheStorage, CacheStoreArgs, CacheStoreInstanceArgs, UpstreamCache } from './types.ts';
 export declare class Cache implements CacheBuilder {
     #private;
     constructor(registry: Registry, cacheMeta: CacheMeta, storage: CacheStorage, upstream?: UpstreamCache);
@@ -22,7 +22,7 @@ export declare class Cache implements CacheBuilder {
      */
     store(args?: CacheStoreArgs): CacheStoreInstanceArgs;
     push(_req: Request): Promise<void>;
-    invalidate(_req: Request): Promise<void>;
+    invalidate(key: string, url: string): Promise<void>;
 }
 export declare class CacheMiddleware {
     #private;

package/dist/cache/cache.js

@@ -1,5 +1,14 @@
 import { createHash } from 'node:crypto';
-import { EtagConditions } from './etag.js';
+import { EtagConditions } from "./etag.js";
+const supportedSemantics = [
+    'options',
+    'head',
+    'get',
+    'post',
+    'put',
+    'delete',
+    'query',
+];
 export class Cache {
     #registry;
     #cacheMeta;
@@ -54,7 +63,14 @@ export class Cache {
     }
     async push(_req) {
     }
-    async invalidate(_req) {
+    async invalidate(key, url) {
+        const promises = [
+            this.#cacheMeta.invalidate(key),
+            this.#storage.invalidate(key),
+        ];
+        if (this.#upstream != null)
+            promises.push(this.upstream.invalidate(url));
+        await Promise.all(promises);
     }
 }
 export class CacheMiddleware {
@@ -78,9 +94,13 @@ export class CacheMiddleware {
             }
             return false;
         });
-        if (descriptor == null) {
+        if (descriptor == null || !supportedSemantics.includes(descriptor.semantics)) {
             return await next();
         }
+        if (descriptor.semantics === 'put' || descriptor.semantics === 'delete') {
+            this.#useInvalidate(descriptor, ctx, next);
+            return;
+        }
         switch (descriptor.args.strategy) {
             case 'http': {
                 await this.#useHTTP(descriptor, ctx, next);
@@ -99,24 +119,58 @@ export class CacheMiddleware {
     /**
      * @todo Implement vary rules.
      */
-    #makeKey(descriptor) {
+    #makeKey(descriptor, ctx) {
+        const { authKey } = ctx;
         const { contentType } = descriptor;
         const { version } = descriptor.args;
         const { name } = descriptor.action;
         const { url } = descriptor.request;
-        return 'v' + (version ?? 0) + '|' + name + '|' + contentType.toLowerCase() + '|' + url.toString();
+        if (authKey == null)
+            return 'v' + (version ?? 0) + '|' + name + '|' + contentType.toLowerCase() + '|' + url.toString();
+        return 'v' + (version ?? 0) + '|' + name + '|' + contentType.toLowerCase() + '|' + url.toString() + '|' + authKey;
     }
+    /**
+     * Sets response headers based of the cache args and authorization status.
+     */
     #setHeaders(descriptor, ctx) {
-        const {} = descriptor.args;
+        const args = descriptor.args;
+        const cacheControl = [];
+        if (ctx.authKey != null && args.publicWhenAuthenticated) {
+            cacheControl.push('public');
+        }
+        else if (ctx.authKey != null || args.private) {
+            cacheControl.push('private');
+        }
+        else if (ctx.public) {
+            cacheControl.push('public');
+        }
+        if (cacheControl.length !== 0) {
+            ctx.headers.set('Cache-Control', cacheControl.join(', '));
+        }
+    }
+    /**
+     * Used for PUT and DELETE requests which should invalidate the cache
+     * when successful.
+     */
+    async #useInvalidate(descriptor, ctx, next) {
+        await next();
+        if (ctx.status != null || ctx.status.toString()[0] !== '2') {
+            return;
+        }
+        const key = this.#makeKey(descriptor, ctx);
+        const args = descriptor.args;
+        const cache = args.cache;
+        await cache.invalidate(key, ctx.url);
     }
     async #useHTTP(descriptor, ctx, next) {
         this.#setHeaders(descriptor, ctx);
         await next();
     }
     async #useEtag(descriptor, ctx, next) {
-        const key = this.#makeKey(descriptor);
+        const key = this.#makeKey(descriptor, ctx);
         const rules = new EtagConditions(ctx.req.headers);
         const resourceState = await descriptor.args.cache.meta.get(key);
+        this.#setHeaders(descriptor, ctx);
         if (resourceState.type === 'cache-hit') {
             if (rules.ifMatch(resourceState.etag)) {
                 return;
@@ -127,64 +181,78 @@ export class CacheMiddleware {
                 return;
             }
         }
-        this.#setHeaders(descriptor, ctx);
         await next();
     }
     async #useStore(descriptor, ctx, next) {
-        const key = this.#makeKey(descriptor);
+        const key = this.#makeKey(descriptor, ctx);
         let resourceState;
-        if (typeof descriptor.args.cache.meta.getOrLock === 'function' &&
-            descriptor.args.lock) {
-            try {
-                resourceState = await descriptor.args.cache.meta.getOrLock(key);
-            }
-            catch (err) {
-                resourceState = await descriptor.args.cache.meta.get(key);
+        const args = descriptor.args;
+        const cache = args.cache;
+        this.#setHeaders(descriptor, ctx);
+        if (descriptor.semantics === 'get' ||
+            descriptor.semantics === 'head' ||
+            descriptor.semantics === 'options' ||
+            descriptor.semantics === 'query') {
+            if (typeof cache.meta.getOrLock === 'function' &&
+                args.lock) {
+                try {
+                    resourceState = await cache.meta.getOrLock(key);
+                }
+                catch (err) {
+                    resourceState = await cache.meta.get(key);
+                }
             }
-        }
-        else {
-            resourceState = await descriptor.args.cache.meta.get(key);
-        }
-        if (resourceState?.type === 'cache-hit') {
-            if (this.#isNotModified(ctx.req.headers, resourceState.etag)) {
-                ctx.hit = true;
-                ctx.status = 304;
-                return;
+            else {
+                resourceState = await cache.meta.get(key);
             }
-            if (resourceState.hasContent) {
-                try {
+            if (resourceState?.type === 'cache-hit') {
+                if (this.#isNotModified(ctx.req.headers, resourceState.etag)) {
                     ctx.hit = true;
-                    ctx.status = resourceState.status;
-                    ctx.body = await descriptor.args.cache.storage.get(key);
-                    for (const [key, value] of resourceState.headers.entries()) {
-                        ctx.headers.set(key, value);
-                    }
+                    ctx.status = 304;
                     return;
                 }
-                catch (err) {
-                    console.log(err);
+                if (resourceState.hasContent) {
+                    try {
+                        ctx.hit = true;
+                        ctx.status = resourceState.status;
+                        ctx.body = await cache.storage.get(key);
+                        for (const [key, value] of Object.entries(resourceState.headers)) {
+                            if (Array.isArray(value)) {
+                                ctx.headers.delete(key);
+                                for (let i = 0; i < value.length; i++) {
+                                    ctx.headers.append(key, value[i]);
+                                }
+                            }
+                            else {
+                                ctx.headers.set(key, value);
+                            }
+                        }
+                        return;
+                    }
+                    catch (err) {
+                        console.log(err);
+                    }
                 }
             }
         }
         try {
-            this.#setHeaders(descriptor, ctx);
             await next();
             const body = await new Response(ctx.body).blob();
             const etag = await this.#createEtag(body);
             ctx.etag = etag;
             ctx.headers.set('Etag', etag);
-            await descriptor.args.cache.meta.set(key, {
+            await cache.meta.set(key, {
                 key,
                 authKey: ctx.authKey,
                 iri: ctx.url,
                 status: ctx.status ?? 200,
                 hasContent: ctx.body != null,
-                headers: ctx.headers,
+                headers: Object.fromEntries(ctx.headers.entries()),
                 contentType: ctx.contentType,
                 etag,
             });
             if (ctx.body != null) {
-                await descriptor.args.cache.storage.set(key, body);
+                await cache.storage.set(key, body);
             }
             if (resourceState.type === 'locked-cache-miss') {
                 await resourceState.release();
@@ -193,7 +261,6 @@ export class CacheMiddleware {
                 ctx.hit = true;
                 ctx.status = 304;
                 ctx.body = null;
-                ctx.headers.delete('Etag');
                 return;
             }
         }
@@ -211,10 +278,12 @@ export class CacheMiddleware {
         const rules = new EtagConditions(headers);
         return rules.isNotModified(etag);
     }
-    async #createEtag(body, weak = true) {
+    /**
+     * Creates a strong etag using a sha1 hashing algorithim.
+     */
+    async #createEtag(body) {
         const buff = await body.bytes();
         const hash = createHash('sha1').update(buff).digest('hex');
-        const quoted = `"${hash}"`;
-        return weak ? `W/${quoted}` : quoted;
+        return `"${hash}"`;
     }
 }

package/dist/cache/etag.test.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { EtagConditions } from './etag.js';
+import { EtagConditions } from "./etag.js";
 test.describe('conditions.ifMatch()', () => {
     test('returns true when the header has the value of "*" and an etag is present', () => {
         const conditions = new EtagConditions(new Headers({