raffel 0.1.2

package/dist/adapters/s3db/utils/guards.js

@@ -0,0 +1,169 @@
+/**
+ * Guards System for S3DB Adapter
+ *
+ * Provides flexible authorization guards supporting:
+ * - Boolean (allow/deny)
+ * - Scope strings with wildcards
+ * - Role-based access
+ * - Custom functions
+ */
+/**
+ * Check if a user has a specific scope, supporting wildcards.
+ *
+ * Wildcards:
+ * - `users:*` matches `users:read`, `users:write`, etc.
+ * - `*` matches everything
+ *
+ * @example
+ * ```ts
+ * hasScope({ scopes: ['users:*'] }, 'users:read')  // true
+ * hasScope({ scopes: ['admin'] }, 'users:read')   // false
+ * hasScope({ scopes: ['*'] }, 'anything')         // true
+ * ```
+ */
+export function hasScope(user, scope) {
+    if (!user?.scopes || !Array.isArray(user.scopes)) {
+        return false;
+    }
+    // Direct match
+    if (user.scopes.includes(scope)) {
+        return true;
+    }
+    // Check wildcards
+    for (const userScope of user.scopes) {
+        // Global wildcard
+        if (userScope === '*') {
+            return true;
+        }
+        // Prefix wildcard (e.g., "users:*" matches "users:read")
+        if (userScope.endsWith(':*')) {
+            const prefix = userScope.slice(0, -2);
+            if (scope.startsWith(prefix + ':') || scope === prefix) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Check if a user has a specific role.
+ *
+ * Checks both `role` (string) and `roles` (array) properties.
+ */
+export function hasRole(user, role) {
+    if (!user)
+        return false;
+    // Check single role property
+    if (user.role === role)
+        return true;
+    // Check roles array
+    if (Array.isArray(user.roles) && user.roles.includes(role))
+        return true;
+    return false;
+}
+/**
+ * Check if a user has any of the specified roles.
+ */
+export function hasAnyRole(user, roles) {
+    return roles.some((role) => hasRole(user, role));
+}
+/**
+ * Check a guard against the context and optional record.
+ *
+ * @returns true if allowed, false if denied
+ */
+export async function checkGuard(guard, ctx, record) {
+    // No guard = allow
+    if (guard === null || guard === undefined) {
+        return true;
+    }
+    // Boolean guard
+    if (typeof guard === 'boolean') {
+        return guard;
+    }
+    // Get user from auth context (auth can be any shape, we just need scopes/roles)
+    const user = ctx.auth;
+    // String = scope check
+    if (typeof guard === 'string') {
+        return hasScope(user, guard);
+    }
+    // Array = any scope matches (OR)
+    if (Array.isArray(guard)) {
+        return guard.some((scope) => hasScope(user, scope));
+    }
+    // Function = custom check
+    if (typeof guard === 'function') {
+        const result = guard(ctx, record);
+        return result instanceof Promise ? await result : result;
+    }
+    // Object = role + scopes + check
+    if (typeof guard === 'object') {
+        const guardObj = guard;
+        // Check role requirement
+        if (guardObj.role) {
+            const requiredRoles = Array.isArray(guardObj.role) ? guardObj.role : [guardObj.role];
+            if (!hasAnyRole(user, requiredRoles)) {
+                return false;
+            }
+        }
+        // Check scopes requirement (ALL must match)
+        if (guardObj.scopes) {
+            const requiredScopes = Array.isArray(guardObj.scopes) ? guardObj.scopes : [guardObj.scopes];
+            if (!requiredScopes.every((scope) => hasScope(user, scope))) {
+                return false;
+            }
+        }
+        // Check custom function
+        if (guardObj.check && typeof guardObj.check === 'function') {
+            const result = guardObj.check(ctx, record);
+            return result instanceof Promise ? await result : result;
+        }
+        // All checks passed
+        return true;
+    }
+    // Unknown type = deny
+    return false;
+}
+/**
+ * Operation aliases for guard resolution.
+ */
+const OPERATION_ALIASES = {
+    list: 'read',
+    get: 'read',
+    count: 'read',
+    head: 'read',
+    create: 'write',
+    update: 'write',
+    patch: 'write',
+    delete: 'write',
+};
+/**
+ * Get the guard for a specific operation, with fallback resolution.
+ *
+ * Resolution order:
+ * 1. Exact operation match (e.g., `guards.list`)
+ * 2. Alias match (e.g., `guards.read` for list/get)
+ * 3. All fallback (e.g., `guards.all`)
+ * 4. No guard (allow)
+ */
+export function getOperationGuard(guards, operation) {
+    if (!guards) {
+        return null;
+    }
+    // 1. Exact match
+    if (guards[operation] !== undefined) {
+        return guards[operation];
+    }
+    // 2. Alias match
+    const alias = OPERATION_ALIASES[operation];
+    if (alias && guards[alias] !== undefined) {
+        return guards[alias];
+    }
+    // 3. All fallback
+    if (guards.all !== undefined) {
+        return guards.all;
+    }
+    // 4. No guard
+    return null;
+}
+//# sourceMappingURL=guards.js.map

package/dist/adapters/s3db/utils/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../../../src/adapters/s3db/utils/guards.ts"],"names":[],"mappings":"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"}

package/dist/adapters/s3db/utils/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * S3DB Adapter Utilities
+ */
+export { generateETag, validateIfMatch, validateIfNoneMatch, formatLastModified, } from './etag.js';
+export { hasScope, hasRole, hasAnyRole, checkGuard, getOperationGuard, } from './guards.js';
+export type { GuardUser, GuardFunction, GuardObject, Guard, GuardsConfig, S3DBOperation, } from './guards.js';
+export { parsePopulate, addPopulatePath, buildIncludesTree, resolvePopulate, hasRelations, getRelationNames, } from './populate.js';
+export type { PopulateResult, IncludesTree, IncludesNode, } from './populate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/s3db/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/s3db/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,WAAW,CAAA;AAGlB,OAAO,EACL,QAAQ,EACR,OAAO,EACP,UAAU,EACV,UAAU,EACV,iBAAiB,GAClB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,SAAS,EACT,aAAa,EACb,WAAW,EACX,KAAK,EACL,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,cAAc,EACd,YAAY,EACZ,YAAY,GACb,MAAM,eAAe,CAAA"}

package/dist/adapters/s3db/utils/index.js

@@ -0,0 +1,10 @@
+/**
+ * S3DB Adapter Utilities
+ */
+// ETag utilities
+export { generateETag, validateIfMatch, validateIfNoneMatch, formatLastModified, } from './etag.js';
+// Guards utilities
+export { hasScope, hasRole, hasAnyRole, checkGuard, getOperationGuard, } from './guards.js';
+// Populate utilities
+export { parsePopulate, addPopulatePath, buildIncludesTree, resolvePopulate, hasRelations, getRelationNames, } from './populate.js';
+//# sourceMappingURL=index.js.map

package/dist/adapters/s3db/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/adapters/s3db/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,WAAW,CAAA;AAElB,mBAAmB;AACnB,OAAO,EACL,QAAQ,EACR,OAAO,EACP,UAAU,EACV,UAAU,EACV,iBAAiB,GAClB,MAAM,aAAa,CAAA;AAUpB,qBAAqB;AACrB,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAA"}

package/dist/adapters/s3db/utils/populate.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Populate Utilities for S3DB Adapter
+ *
+ * Handles parsing and validation of relation population
+ * for expanding related records in responses.
+ */
+import type { S3DBResourceLike } from '../types.js';
+/**
+ * Result of parsing and validating populate parameter.
+ */
+export interface PopulateResult {
+    /** Validated includes tree for s3db.js relations */
+    includes?: IncludesTree;
+    /** Validation errors */
+    errors?: string[];
+}
+/**
+ * Includes tree for s3db.js relations.
+ *
+ * @example
+ * ```ts
+ * // "author" → { author: true }
+ * // "comments.user" → { comments: { include: { user: true } } }
+ * ```
+ */
+export type IncludesTree = Record<string, boolean | IncludesNode>;
+export interface IncludesNode {
+    include: IncludesTree;
+}
+/**
+ * Parse populate query string into paths array.
+ *
+ * @example
+ * ```ts
+ * parsePopulate('author,comments.user')
+ * // => ['author', 'comments.user']
+ *
+ * parsePopulate('author, tags, comments.user')
+ * // => ['author', 'tags', 'comments.user']
+ * ```
+ */
+export declare function parsePopulate(query: string | string[] | undefined | null): string[];
+/**
+ * Add a populate path to the includes tree.
+ *
+ * @example
+ * ```ts
+ * const tree = {}
+ * addPopulatePath(tree, ['author'])
+ * // tree = { author: true }
+ *
+ * addPopulatePath(tree, ['comments', 'user'])
+ * // tree = { author: true, comments: { include: { user: true } } }
+ * ```
+ */
+export declare function addPopulatePath(tree: IncludesTree, parts: string[]): void;
+/**
+ * Build includes tree from populate paths.
+ *
+ * @example
+ * ```ts
+ * buildIncludesTree(['author', 'comments.user'])
+ * // => {
+ * //   author: true,
+ * //   comments: { include: { user: true } }
+ * // }
+ * ```
+ */
+export declare function buildIncludesTree(paths: string[]): IncludesTree;
+/**
+ * Resolve populate paths against resource relations.
+ *
+ * Validates that all requested paths exist as defined relations.
+ *
+ * @param resource - The source resource
+ * @param paths - Populate paths to resolve
+ * @param getResource - Function to get related resources by name
+ * @returns PopulateResult with includes tree or errors
+ */
+export declare function resolvePopulate(resource: S3DBResourceLike, paths: string[], getResource?: (name: string) => S3DBResourceLike | undefined): PopulateResult;
+/**
+ * Check if resource has relations defined.
+ */
+export declare function hasRelations(resource: S3DBResourceLike): boolean;
+/**
+ * Get available relation names for a resource.
+ */
+export declare function getRelationNames(resource: S3DBResourceLike): string[];
+//# sourceMappingURL=populate.d.ts.map

package/dist/adapters/s3db/utils/populate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"populate.d.ts","sourceRoot":"","sources":["../../../../src/adapters/s3db/utils/populate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAA0B,MAAM,aAAa,CAAA;AAE3E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAAC,CAAA;AAEjE,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,YAAY,CAAA;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,EAAE,CAUnF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAgCzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,CAW/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,MAAM,EAAE,EACf,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,GAC3D,cAAc,CAyDhB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAGhE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAGrE"}

package/dist/adapters/s3db/utils/populate.js

@@ -0,0 +1,165 @@
+/**
+ * Populate Utilities for S3DB Adapter
+ *
+ * Handles parsing and validation of relation population
+ * for expanding related records in responses.
+ */
+/**
+ * Parse populate query string into paths array.
+ *
+ * @example
+ * ```ts
+ * parsePopulate('author,comments.user')
+ * // => ['author', 'comments.user']
+ *
+ * parsePopulate('author, tags, comments.user')
+ * // => ['author', 'tags', 'comments.user']
+ * ```
+ */
+export function parsePopulate(query) {
+    if (!query)
+        return [];
+    // Handle array input (e.g., from query params)
+    const values = Array.isArray(query) ? query : [query];
+    return values
+        .flatMap((v) => String(v).split(','))
+        .map((v) => v.trim())
+        .filter(Boolean);
+}
+/**
+ * Add a populate path to the includes tree.
+ *
+ * @example
+ * ```ts
+ * const tree = {}
+ * addPopulatePath(tree, ['author'])
+ * // tree = { author: true }
+ *
+ * addPopulatePath(tree, ['comments', 'user'])
+ * // tree = { author: true, comments: { include: { user: true } } }
+ * ```
+ */
+export function addPopulatePath(tree, parts) {
+    if (!parts.length)
+        return;
+    const [head, ...rest] = parts;
+    if (!head)
+        return;
+    const existing = tree[head];
+    // Leaf node (no more nesting)
+    if (rest.length === 0) {
+        // Don't overwrite existing nested structure with boolean
+        if (existing && typeof existing === 'object') {
+            return;
+        }
+        tree[head] = true;
+        return;
+    }
+    // Nested path - ensure we have an IncludesNode
+    let node;
+    if (!existing || existing === true) {
+        node = { include: {} };
+        tree[head] = node;
+    }
+    else {
+        node = existing;
+        if (!node.include || typeof node.include !== 'object') {
+            node.include = {};
+        }
+    }
+    // Recurse
+    addPopulatePath(node.include, rest);
+}
+/**
+ * Build includes tree from populate paths.
+ *
+ * @example
+ * ```ts
+ * buildIncludesTree(['author', 'comments.user'])
+ * // => {
+ * //   author: true,
+ * //   comments: { include: { user: true } }
+ * // }
+ * ```
+ */
+export function buildIncludesTree(paths) {
+    const tree = {};
+    for (const path of paths) {
+        const segments = path.split('.').map((s) => s.trim()).filter(Boolean);
+        if (segments.length > 0) {
+            addPopulatePath(tree, segments);
+        }
+    }
+    return tree;
+}
+/**
+ * Resolve populate paths against resource relations.
+ *
+ * Validates that all requested paths exist as defined relations.
+ *
+ * @param resource - The source resource
+ * @param paths - Populate paths to resolve
+ * @param getResource - Function to get related resources by name
+ * @returns PopulateResult with includes tree or errors
+ */
+export function resolvePopulate(resource, paths, getResource) {
+    if (!paths.length) {
+        return {};
+    }
+    const errors = [];
+    const validPaths = [];
+    for (const path of paths) {
+        const segments = path.split('.').map((s) => s.trim()).filter(Boolean);
+        if (segments.length === 0)
+            continue;
+        let currentResource = resource;
+        let isValid = true;
+        for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i];
+            if (!segment)
+                continue;
+            // Get relations from resource
+            const relations = currentResource._relations;
+            if (!relations || !relations[segment]) {
+                errors.push(`Relation "${segment}" is not defined on resource "${currentResource.name}" (path "${path}")`);
+                isValid = false;
+                break;
+            }
+            // For nested paths, we need to traverse to the related resource
+            if (i < segments.length - 1 && getResource) {
+                const relationConfig = relations[segment];
+                const relatedResource = getResource(relationConfig.resource);
+                if (!relatedResource) {
+                    errors.push(`Related resource "${relationConfig.resource}" for relation "${segment}" not found (path "${path}")`);
+                    isValid = false;
+                    break;
+                }
+                currentResource = relatedResource;
+            }
+        }
+        if (isValid) {
+            validPaths.push(path);
+        }
+    }
+    if (errors.length > 0) {
+        return { errors };
+    }
+    return {
+        includes: buildIncludesTree(validPaths),
+    };
+}
+/**
+ * Check if resource has relations defined.
+ */
+export function hasRelations(resource) {
+    const relations = resource._relations;
+    return !!relations && Object.keys(relations).length > 0;
+}
+/**
+ * Get available relation names for a resource.
+ */
+export function getRelationNames(resource) {
+    const relations = resource._relations;
+    return relations ? Object.keys(relations) : [];
+}
+//# sourceMappingURL=populate.js.map

package/dist/adapters/s3db/utils/populate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"populate.js","sourceRoot":"","sources":["../../../../src/adapters/s3db/utils/populate.ts"],"names":[],"mappings":"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"}

package/dist/adapters/tcp.d.ts

@@ -0,0 +1,59 @@
+/**
+ * TCP Adapter
+ *
+ * Exposes Raffel services over raw TCP with length-prefixed framing.
+ * Ideal for high-performance service-to-service communication.
+ *
+ * Protocol:
+ *   [4 bytes: length (big-endian uint32)] [N bytes: JSON payload]
+ *
+ * Messages follow the same envelope format as WebSocket.
+ */
+import { type Server, type Socket } from 'node:net';
+import type { Router } from '../core/router.js';
+import type { Context } from '../types/index.js';
+/**
+ * TCP adapter configuration
+ */
+export interface TcpAdapterOptions {
+    /** Port to listen on */
+    port: number;
+    /** Host to bind to (default: '0.0.0.0') */
+    host?: string;
+    /** Maximum message size in bytes (default: 16MB) */
+    maxMessageSize?: number;
+    /** Keep-alive interval in ms (default: 30000, 0 to disable) */
+    keepAliveInterval?: number;
+    /** Context factory for creating request context */
+    contextFactory?: (socket: Socket) => Partial<Context>;
+}
+/**
+ * TCP Adapter interface
+ */
+export interface TcpAdapter {
+    /** Start the server */
+    start(): Promise<void>;
+    /** Stop the server */
+    stop(): Promise<void>;
+    /** Get connected client count */
+    readonly clientCount: number;
+    /** Get the underlying server (for testing) */
+    readonly server: Server | null;
+}
+/**
+ * Create a TCP adapter
+ */
+export declare function createTcpAdapter(router: Router, options: TcpAdapterOptions): TcpAdapter;
+/**
+ * Helper: Create a TCP client for testing/usage
+ * This is a simple client implementation for the length-prefixed protocol
+ */
+export declare function createTcpClient(options: {
+    host: string;
+    port: number;
+}): {
+    connect(): Promise<void>;
+    call(procedure: string, payload: unknown): Promise<unknown>;
+    disconnect(): void;
+};
+//# sourceMappingURL=tcp.d.ts.map

package/dist/adapters/tcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tcp.d.ts","sourceRoot":"","sources":["../../src/adapters/tcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAkC,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAA;AAEnF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAY,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAa1D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAA;IAEZ,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B,mDAAmD;IACnD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACtD;AAaD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,uBAAuB;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB,sBAAsB;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAErB,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GACzB,UAAU,CAoWZ;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;eAUlD,OAAO,CAAC,IAAI,CAAC;oBA8CR,MAAM,WAAW,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;kBAkCnD,IAAI;EAQrB"}

package/dist/adapters/tcp.int.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * TCP Adapter Tests
+ */
+export {};
+//# sourceMappingURL=tcp.int.test.d.ts.map

package/dist/adapters/tcp.int.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tcp.int.test.d.ts","sourceRoot":"","sources":["../../src/adapters/tcp.int.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}