@occultist/occultist 0.0.1

package/dist/actions/writer.js

@@ -0,0 +1,140 @@
+import { ServerResponse } from 'node:http';
+function isHintLink(hint) {
+    return hint.href != null;
+}
+;
+export class ResponseWriter {
+    #res;
+    #hints;
+    #status;
+    #statusText;
+    #headers = new Headers();
+    #body;
+    constructor(res) {
+        this.#res = res;
+    }
+    /**
+     * Writes early hints to the request.
+     *
+     * Runtimes which do not support writing early hints will have the
+     * headers added to the headers of the main response instead.
+     */
+    writeEarlyHints(args) {
+        const links = [];
+        if (Array.isArray(args)) {
+            for (let i = 0; i < args.length; i++) {
+                links.push(this.#formatEarlyHint(args[i]));
+            }
+        }
+        else if (typeof args === 'function') {
+            const res = args();
+            if (Array.isArray(res)) {
+                for (let i = 0; i < res.length; i++) {
+                    links.push(this.#formatEarlyHint(res[i]));
+                }
+            }
+            else if (isHintLink(res)) {
+                links.push(this.#formatEarlyHint(res));
+            }
+            else if (Array.isArray(res.link)) {
+                for (let i = 0; i < res.link.length; i++) {
+                    links.push(this.#formatEarlyHint(res.link[i]));
+                }
+            }
+            else {
+                links.push(this.#formatEarlyHint(res.link));
+            }
+        }
+        else if (isHintLink(args)) {
+            links.push(this.#formatEarlyHint(args));
+        }
+        else if (Array.isArray(args.link)) {
+            for (let i = 0; i < args.link.length; i++) {
+                links.push(this.#formatEarlyHint(args.link[i]));
+            }
+        }
+        else {
+            links.push(this.#formatEarlyHint(args.link));
+        }
+        if (this.#res == null) {
+            this.#headers.append('Link', links.join(', '));
+        }
+        else {
+            return new Promise((resolve) => {
+                this.#res.writeEarlyHints({ 'Link': links.join(', ') }, resolve);
+            });
+        }
+    }
+    mergeHeaders(headersInit) {
+        this.#setHeaders(new Headers(headersInit));
+    }
+    writeHead(status, headers) {
+        const res = this.#res;
+        this.#status = status;
+        if (headers != null) {
+            this.#setHeaders(headers);
+        }
+        if (res instanceof ServerResponse && this.#hints != null) {
+            res.writeHead(status, this.#hints);
+        }
+        else if (res instanceof ServerResponse) {
+            res.writeHead(status);
+        }
+    }
+    writeBody(body) {
+        if (this.#res instanceof ServerResponse) {
+            this.#res.write(body);
+        }
+        else {
+            this.#body = body;
+        }
+    }
+    response() {
+        if (this.#res instanceof ServerResponse) {
+            this.#res.end();
+            return this.#res;
+        }
+        if (this.#body instanceof Uint8Array) {
+        }
+        return new Response(this.#body, {
+            status: this.#status,
+            statusText: this.#statusText,
+            headers: this.#headers,
+        });
+    }
+    #setHeaders(headers) {
+        for (const [header, value] of headers.entries()) {
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    this.#headers.append(header, item);
+                }
+            }
+            else {
+                this.#headers.append(header, value);
+            }
+        }
+    }
+    #formatEarlyHint(hint) {
+        let link = `<${encodeURI(hint.href)}>`;
+        if (hint.preload) {
+            link += `; rel=preload`;
+        }
+        if (Array.isArray(hint.rel)) {
+            link += '; ' + hint.rel.map((rel) => `rel=${rel}`)
+                .join('; ') + '';
+        }
+        else if (hint.rel != null) {
+            link += `; rel=${hint.rel}`;
+        }
+        if (hint.as != null) {
+            link += `; as=${hint.as}`;
+        }
+        if (hint.fetchPriority != null) {
+            link += `; fetchpriority=${hint.fetchPriority}`;
+        }
+        if (hint.crossOrigin != null) {
+            link += `; crossorigin=${hint.crossOrigin}`;
+        }
+        return link;
+    }
+}

package/dist/actions/writer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/actions/writer.test.js

@@ -0,0 +1,42 @@
+import { createServer } from 'node:http';
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { ResponseWriter } from './writer.js';
+test('Writer writes hints', () => {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.on('request', async (_req, res) => {
+            const writer = new ResponseWriter(res);
+            await writer.writeEarlyHints({
+                link: [
+                    {
+                        href: 'https://example.com/main.css',
+                        as: 'stylesheet',
+                        preload: true,
+                        fetchPriority: 'high',
+                    },
+                    {
+                        href: 'https://example.com/main.js',
+                        as: 'script',
+                        preload: true,
+                        fetchPriority: 'low',
+                    }
+                ],
+            });
+            writer.writeHead(200);
+            res.end();
+        });
+        server.on('error', (err) => {
+            reject(err);
+        });
+        server.listen(0, '127.0.0.1', async () => {
+            const { port, address } = server.address();
+            const res = await fetch(`http://${address}:${port}`);
+            await res.text();
+            assert(res.headers.get('link'), `</https://example.com/main.css>; rel=preload; as=stylesheet; fetchpriority=high, `
+                + `</https://example.com/main.js>; rel=preload; as=script; fetchpriority=low`);
+            server.close();
+            resolve();
+        });
+    });
+});

package/dist/auth/types.d.ts

@@ -0,0 +1,14 @@
+export type UnauthenticatedAuthContext = {
+    authenticated: false;
+    authKey: undefined;
+};
+export type AuthenticatedAuthContext = {
+    authenticated: true;
+    authKey: string;
+};
+export type AuthState = Record<string, any>;
+export type AuthMiddlewareResponse<State extends AuthState = AuthState> = {
+    authKey?: string;
+    allowPublic?: boolean;
+    state: State;
+};

package/dist/auth/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cache/cache.d.ts

@@ -0,0 +1,30 @@
+import { CacheContext, NextFn, Registry } from '../mod.js';
+import type { CacheBuilder, CacheEntryDescriptor, CacheETagArgs, CacheETagInstanceArgs, CacheHTTPArgs, CacheHTTPInstanceArgs, CacheMeta, CacheStorage, CacheStoreArgs, CacheStoreInstanceArgs, UpstreamCache } from './types.js';
+export declare class Cache implements CacheBuilder {
+    #private;
+    constructor(registry: Registry, cacheMeta: CacheMeta, storage: CacheStorage, upstream?: UpstreamCache);
+    get registry(): Registry;
+    get meta(): CacheMeta;
+    get storage(): CacheStorage;
+    get upstream(): UpstreamCache;
+    /**
+     * Add HTTP headers to the request.
+     */
+    http(args?: CacheHTTPArgs): CacheHTTPInstanceArgs;
+    /**
+     * Stores an etag value of the response and adds HTTP headers to the request.
+     * Requests made to an endpoint implementing etag cache can use `If-None-Match`
+     * or `If-Modified-Since` headers to test
+     */
+    etag(args?: CacheETagArgs): CacheETagInstanceArgs;
+    /**
+     * Caches the body of the response, stores and etag and adds HTTP headers to the request.
+     */
+    store(args?: CacheStoreArgs): CacheStoreInstanceArgs;
+    push(_req: Request): Promise<void>;
+    invalidate(_req: Request): Promise<void>;
+}
+export declare class CacheMiddleware {
+    #private;
+    use(descriptors: CacheEntryDescriptor[], ctx: CacheContext, next: NextFn): Promise<void>;
+}

package/dist/cache/cache.js

@@ -0,0 +1,220 @@
+import { createHash } from 'node:crypto';
+import { EtagConditions } from './etag.js';
+export class Cache {
+    #registry;
+    #cacheMeta;
+    #storage;
+    #upstream;
+    constructor(registry, cacheMeta, storage, upstream) {
+        this.#registry = registry;
+        this.#cacheMeta = cacheMeta;
+        this.#storage = storage;
+        this.#upstream = upstream;
+    }
+    get registry() {
+        return this.#registry;
+    }
+    get meta() {
+        return this.#cacheMeta;
+    }
+    get storage() {
+        return this.#storage;
+    }
+    get upstream() {
+        return this.#upstream;
+    }
+    /**
+     * Add HTTP headers to the request.
+     */
+    http(args) {
+        return Object.assign(Object.create(null), args, {
+            strategy: 'http',
+            cache: this,
+        });
+    }
+    /**
+     * Stores an etag value of the response and adds HTTP headers to the request.
+     * Requests made to an endpoint implementing etag cache can use `If-None-Match`
+     * or `If-Modified-Since` headers to test
+     */
+    etag(args) {
+        return Object.assign(Object.create(null), args, {
+            strategy: 'etag',
+            cache: this,
+        });
+    }
+    /**
+     * Caches the body of the response, stores and etag and adds HTTP headers to the request.
+     */
+    store(args) {
+        return Object.assign(Object.create(null), args, {
+            strategy: 'store',
+            cache: this,
+        });
+    }
+    async push(_req) {
+    }
+    async invalidate(_req) {
+    }
+}
+export class CacheMiddleware {
+    async use(descriptors, ctx, next) {
+        const descriptor = descriptors.find((descriptor) => {
+            const when = descriptor.args.when;
+            if (when == null) {
+                return true;
+            }
+            else if (when === 'always') {
+                return true;
+            }
+            else if (when === 'public' && ctx.authKey == null) {
+                return true;
+            }
+            else if (when === 'private' && ctx.authKey != null) {
+                return true;
+            }
+            else if (typeof when === 'function') {
+                return when(ctx);
+            }
+            return false;
+        });
+        if (descriptor == null) {
+            return await next();
+        }
+        switch (descriptor.args.strategy) {
+            case 'http': {
+                await this.#useHTTP(descriptor, ctx, next);
+                break;
+            }
+            case 'etag': {
+                await this.#useEtag(descriptor, ctx, next);
+                break;
+            }
+            case 'store': {
+                await this.#useStore(descriptor, ctx, next);
+                break;
+            }
+        }
+    }
+    /**
+     * @todo Implement vary rules.
+     */
+    #makeKey(descriptor) {
+        const { contentType } = descriptor;
+        const { version } = descriptor.args;
+        const { name } = descriptor.action;
+        const { url } = descriptor.request;
+        return 'v' + (version ?? 0) + '|' + name + '|' + contentType.toLowerCase() + '|' + url.toString();
+    }
+    #setHeaders(descriptor, ctx) {
+        const {} = descriptor.args;
+    }
+    async #useHTTP(descriptor, ctx, next) {
+        this.#setHeaders(descriptor, ctx);
+        await next();
+    }
+    async #useEtag(descriptor, ctx, next) {
+        const key = this.#makeKey(descriptor);
+        const rules = new EtagConditions(ctx.req.headers);
+        const resourceState = await descriptor.args.cache.meta.get(key);
+        if (resourceState.type === 'cache-hit') {
+            if (rules.ifMatch(resourceState.etag)) {
+                return;
+            }
+            else if (!rules.ifNoneMatch(resourceState.etag)) {
+                ctx.hit = true;
+                ctx.status = 304;
+                return;
+            }
+        }
+        this.#setHeaders(descriptor, ctx);
+        await next();
+    }
+    async #useStore(descriptor, ctx, next) {
+        const key = this.#makeKey(descriptor);
+        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);
+            }
+        }
+        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;
+            }
+            if (resourceState.hasContent) {
+                try {
+                    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);
+                    }
+                    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, {
+                key,
+                authKey: ctx.authKey,
+                iri: ctx.url,
+                status: ctx.status ?? 200,
+                hasContent: ctx.body != null,
+                headers: ctx.headers,
+                contentType: ctx.contentType,
+                etag,
+            });
+            if (ctx.body != null) {
+                await descriptor.args.cache.storage.set(key, body);
+            }
+            if (resourceState.type === 'locked-cache-miss') {
+                await resourceState.release();
+            }
+            if (this.#isNotModified(ctx.req.headers, etag)) {
+                ctx.hit = true;
+                ctx.status = 304;
+                ctx.body = null;
+                ctx.headers.delete('Etag');
+                return;
+            }
+        }
+        catch (err) {
+            if (resourceState.type === 'locked-cache-miss') {
+                await resourceState.release();
+            }
+        }
+    }
+    /**
+     * Returns true if the request has conditional headers
+     * which should result in a not modified response.
+     */
+    #isNotModified(headers, etag) {
+        const rules = new EtagConditions(headers);
+        return rules.isNotModified(etag);
+    }
+    async #createEtag(body, weak = true) {
+        const buff = await body.bytes();
+        const hash = createHash('sha1').update(buff).digest('hex');
+        const quoted = `"${hash}"`;
+        return weak ? `W/${quoted}` : quoted;
+    }
+}

package/dist/cache/etag.d.ts

@@ -0,0 +1,17 @@
+export declare class EtagConditions {
+    headers: Headers;
+    constructor(headers: Headers);
+    /**
+     * Returns true if the representation is not modified based of
+     * conditional headers and the value of the current representation's
+     * etag. True results should result in a 304 response.
+     *
+     * @param representationEtag - The current etag value for this representation.
+     */
+    isNotModified(representationEtag?: string): boolean;
+    ifMatch(representationEtag?: string): boolean;
+    ifNoneMatch(representationEtag?: string): boolean;
+    ifModifiedSince(): never;
+    ifUnmodifiedSince(): never;
+    ifRange(): never;
+}

package/dist/cache/etag.js

@@ -0,0 +1,83 @@
+export class EtagConditions {
+    headers;
+    constructor(headers) {
+        this.headers = headers;
+    }
+    /**
+     * Returns true if the representation is not modified based of
+     * conditional headers and the value of the current representation's
+     * etag. True results should result in a 304 response.
+     *
+     * @param representationEtag - The current etag value for this representation.
+     */
+    isNotModified(representationEtag) {
+        if (this.headers.has('If-Match')) {
+            return this.ifMatch(representationEtag);
+        }
+        else if (this.headers.has('If-None-Match')) {
+            return !this.ifNoneMatch(representationEtag);
+        }
+        return false;
+    }
+    ifMatch(representationEtag) {
+        let etag;
+        const header = this.headers.get('If-Match');
+        if (header == null) {
+            return true;
+        }
+        else if (header.trim() === '*') {
+            return representationEtag != null;
+        }
+        const etags = header.split?.(',');
+        if (etags.length === 0) {
+            return true;
+        }
+        else if (representationEtag == null) {
+            return false;
+        }
+        for (let i = 0; i < etags.length; i++) {
+            etag = etags[i].trim();
+            // If-Match ignores weak etags
+            if (etag.startsWith('W\/')) {
+                continue;
+            }
+            else if (etag === representationEtag) {
+                return true;
+            }
+        }
+        return false;
+    }
+    ifNoneMatch(representationEtag) {
+        let etag;
+        const header = this.headers.get('If-None-Match');
+        if (header == null || representationEtag == null) {
+            return true;
+        }
+        const etags = header.split?.(',');
+        if (etags.length === 0) {
+            return true;
+        }
+        if (etags[0] === '*') {
+            return representationEtag == null;
+        }
+        for (let i = 0; i < etags.length; i++) {
+            etag = etags[i].trim();
+            if (!etag.startsWith('W\/')) {
+                continue;
+            }
+            else if (etag === representationEtag) {
+                return false;
+            }
+        }
+        return true;
+    }
+    ifModifiedSince() {
+        throw new Error('Not implemented');
+    }
+    ifUnmodifiedSince() {
+        throw new Error('Not implemented');
+    }
+    ifRange() {
+        throw new Error('Not implemented');
+    }
+}

package/dist/cache/etag.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cache/etag.test.js

@@ -0,0 +1,91 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+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({
+            'If-Match': '*',
+        }));
+        assert(conditions.ifMatch('"xxxx"'));
+    });
+    test('returns false when the header has the value of "*" and an etag is not present', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-Match': '*',
+        }));
+        assert(!conditions.ifMatch());
+    });
+    test('returns false when the header provides an etag and an etag is not present', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-Match': '"xxxx"',
+        }));
+        assert(!conditions.ifMatch());
+    });
+    test('returns false when the header provides an etag and a different etag is present', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-Match': '"xxxx"',
+        }));
+        assert(!conditions.ifMatch('"yyyy"'));
+    });
+    test('returns false when the header provides a matching but weak etag', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-Match': 'W\/"xxxx"',
+        }));
+        assert(!conditions.ifMatch('W\/"xxxx"'));
+    });
+    test('returns true when the header provides a matching etag', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-Match': '"xxxx"',
+        }));
+        assert(conditions.ifMatch('"xxxx"'));
+    });
+    test('returns true when the header provides a list containing a matching etag', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-Match': '"xxxx", "yyyy", "zzzz"',
+        }));
+        assert(conditions.ifMatch('"yyyy"'));
+    });
+});
+test.describe('conditions.ifNoneMatch()', () => {
+    test('returns true when the header has the value of "*" and an etag is not present', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-None-Match': '*',
+        }));
+        assert(conditions.ifNoneMatch());
+    });
+    test('returns false when the header has the value of "*" and an etag is present', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-None-Match': '*',
+        }));
+        assert(!conditions.ifNoneMatch('W\/"xxxx"'));
+    });
+    test('returns true when the header provides an etag and no representation etag is present', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-None-Match': 'W\/"xxxx"',
+        }));
+        assert(conditions.ifNoneMatch());
+    });
+    test('returns true when the header provides a non-matching etag', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-None-Match': 'W\/"xxxx"',
+        }));
+        assert(conditions.ifNoneMatch('W\/"yyyy"'));
+    });
+    test('returns true when the header provides a non-matching but strong etag', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-None-Match': '"yyyy"',
+        }));
+        assert(conditions.ifNoneMatch('"xxxx"'));
+    });
+    test('returns false when the header provides a matching etag', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-None-Match': 'W\/"xxxx"',
+        }));
+        assert(!conditions.ifNoneMatch('W\/"xxxx"'));
+    });
+    test('returns false when the header provides a list containing a matching etag', () => {
+        const conditions = new EtagConditions(new Headers({
+            'If-None-Match': 'W\/"xxxx", W\/"yyyy", W\/"zzzz"',
+        }));
+        assert(!conditions.ifNoneMatch('W\/"yyyy"'));
+    });
+});

package/dist/cache/memory.d.ts

@@ -0,0 +1,12 @@
+import type { CacheDetails, CacheHitHandle, CacheMeta, CacheStorage, CacheMissHandle } from './types.js';
+export declare class InMemoryCacheMeta implements CacheMeta {
+    #private;
+    get(key: string): Promise<CacheHitHandle | CacheMissHandle>;
+    set(key: string, details: CacheDetails): Promise<void>;
+}
+export declare class InMemoryCacheStorage implements CacheStorage {
+    #private;
+    get(key: string): Blob;
+    set(key: string, value: Blob): void;
+    invalidate(key: string): void;
+}