@aws-blocks/core 0.1.0

package/dist/raw-route.js

@@ -0,0 +1,239 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { BLOCKS_NAMESPACE, BLOCKS_RPC_PREFIX } from './constants.js';
+/**
+ * Typed error constants for RawRoute. Use with `isBlocksError()` in catch blocks.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   new RawRoute(scope, 'dup', { method: 'GET', path: '/health', handler });
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, RawRouteErrors.DuplicateRoute)) {
+ *     // same method+path already registered
+ *   }
+ * }
+ * ```
+ */
+export const RawRouteErrors = {
+    DuplicateRoute: 'DuplicateRouteException',
+};
+// ── Scope-chain path derivation ─────────────────────────────────────────────
+/**
+ * Derive a URL path from the scope chain.
+ *
+ * Walks the parent chain from `scope` up to (but NOT including) the root
+ * BlocksStack or the top-level user Scope, collects each intermediate scope's
+ * `id`, URL-encodes segments, and joins with `/`. The RawRoute's own `id`
+ * is appended as the final segment.
+ *
+ * A scope is "root-level" if its parent has no `parent` property (i.e., it's
+ * the BlocksStack or the fallback `{ id: ... }` sentinel). Root-level scopes
+ * are excluded from the path — they represent the application boundary, not
+ * a URL segment.
+ *
+ * @example
+ * ```
+ * Scope('app') → RawRoute('health')                    → /health
+ * Scope('app') → Scope('v1') → RawRoute('users')       → /v1/users
+ * Scope('app') → Scope('api') → Scope('v2') → RawRoute('items') → /api/v2/items
+ * ```
+ */
+export function derivePathFromScope(scope, id) {
+    const segments = [];
+    let current = scope;
+    while (current && 'parent' in current && current.parent) {
+        const parentNode = current.parent;
+        const parentIsRoot = !('parent' in parentNode) || !parentNode.parent;
+        if (parentIsRoot)
+            break;
+        segments.unshift(encodeURIComponent(current.id));
+        current = parentNode;
+    }
+    segments.push(encodeURIComponent(id));
+    return '/' + segments.join('/');
+}
+/**
+ * Resolve the effective path for a RawRoute — uses the explicit `path` if
+ * provided, otherwise derives it from the scope chain.
+ */
+export function resolveRoutePath(scope, id, options) {
+    return options.path ?? derivePathFromScope(scope, id);
+}
+const routeRegistry = [];
+let registrationLocked = false;
+const VALID_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']);
+/** Prevent further route registration. Call after initialization is complete. */
+export function lockRouteRegistry() {
+    registrationLocked = true;
+}
+/** Re-allow route registration (useful in tests after lock). */
+export function unlockRouteRegistry() {
+    registrationLocked = false;
+}
+/**
+ * Register a raw HTTP route for runtime dispatch.
+ *
+ * **Internal.** The public API is `new RawRoute(scope, id, options)`.
+ * Path must be resolved before calling this function.
+ *
+ * @throws If registration is locked (after handler creation).
+ * @throws If the HTTP method is invalid.
+ * @throws If the path is under the reserved namespace (`/aws-blocks` or `/aws-blocks/api/*`).
+ * @throws {RawRouteErrors.DuplicateRoute} If the same method+path is registered twice.
+ */
+export function registerRoute(options) {
+    if (registrationLocked) {
+        throw new Error('Routes must be registered during initialization. Cannot register routes after handler creation.');
+    }
+    if (!VALID_METHODS.has(options.method)) {
+        throw new Error(`Invalid HTTP method: ${options.method}. Must be one of: ${Array.from(VALID_METHODS).join(', ')}`);
+    }
+    const normalizedPath = options.path.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+    if (normalizedPath === '/') {
+        throw new Error("Cannot register RawRoute at '/' — root path is not supported (API Gateway proxy resource doesn't handle root). Use a sub-path like '/health'.");
+    }
+    const lowerPath = normalizedPath.toLowerCase();
+    if (lowerPath === BLOCKS_NAMESPACE || lowerPath === BLOCKS_RPC_PREFIX || lowerPath.startsWith(`${BLOCKS_RPC_PREFIX}/`)) {
+        throw new Error(`Cannot register RawRoute at ${BLOCKS_NAMESPACE} or ${BLOCKS_RPC_PREFIX}/* — these paths are reserved for RPC dispatch`);
+    }
+    const existing = routeRegistry.find((r) => r.method === options.method && r.path === normalizedPath);
+    if (existing) {
+        const err = new Error(`${RawRouteErrors.DuplicateRoute}: ${options.method} ${normalizedPath} is already registered`);
+        err.name = RawRouteErrors.DuplicateRoute;
+        throw err;
+    }
+    const { pattern, paramNames } = compilePath(normalizedPath);
+    routeRegistry.push({
+        method: options.method,
+        path: normalizedPath,
+        pattern,
+        paramNames,
+        handler: options.handler,
+    });
+}
+/** Return a read-only snapshot of all registered routes. */
+export function getRegisteredRoutes() {
+    return routeRegistry;
+}
+/** Remove all registered routes and unlock registration (used by tests). */
+export function clearRouteRegistry() {
+    routeRegistry.length = 0;
+    registrationLocked = false;
+}
+/**
+ * Match an incoming HTTP request against registered routes.
+ *
+ * @returns The matched route and extracted path parameters, or `null` if no match.
+ */
+export function matchRoute(method, path) {
+    // Normalize incoming path: collapse double slashes
+    path = path.replace(/\/+/g, '/');
+    for (const route of routeRegistry) {
+        if (route.method !== method)
+            continue;
+        const match = route.pattern.exec(path);
+        if (match) {
+            return { route, params: extractParams(route, match) };
+        }
+        // Retry without trailing slash for non-root paths (e.g. /health/ → /health)
+        if (path.length > 1 && path.endsWith('/')) {
+            const trimmed = path.slice(0, -1);
+            const retryMatch = route.pattern.exec(trimmed);
+            if (retryMatch) {
+                return { route, params: extractParams(route, retryMatch) };
+            }
+        }
+    }
+    return null;
+}
+function extractParams(route, match) {
+    const params = Object.create(null);
+    route.paramNames.forEach((name, i) => {
+        const raw = match[i + 1];
+        if (name === '*') {
+            // Wildcards capture raw paths — no decoding (prevents path traversal)
+            params[name] = raw;
+            return;
+        }
+        // Named params get decoded
+        try {
+            params[name] = decodeURIComponent(raw);
+        }
+        catch {
+            // Invalid percent encoding — use raw value
+            params[name] = raw;
+        }
+    });
+    return params;
+}
+// ── Path compilation ────────────────────────────────────────────────────────
+const REGEX_SPECIAL = new Set(['.', '+', '?', '^', '$', '|', '(', ')', '[', ']', '\\']);
+const BLOCKED_PARAM_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * Compile a path pattern into a RegExp and extract parameter names.
+ *
+ * Supported syntax:
+ * - `/health`        → exact match
+ * - `/users/{id}`    → captures one path segment as `id`
+ * - `/v1/*`          → captures everything after `/v1/` as `*`
+ * - `/a/{x}/b/{y}`   → multiple named parameters
+ */
+export function compilePath(path) {
+    if (!path.startsWith('/')) {
+        throw new Error('Path must start with /');
+    }
+    // Normalize: collapse double slashes
+    path = path.replace(/\/+/g, '/');
+    // Remove trailing slash (except root '/')
+    if (path.length > 1 && path.endsWith('/')) {
+        path = path.slice(0, -1);
+    }
+    const paramNames = [];
+    let regexStr = '';
+    let i = 0;
+    let wildcardCount = 0;
+    while (i < path.length) {
+        if (path[i] === '{') {
+            const end = path.indexOf('}', i);
+            if (end === -1) {
+                throw new Error(`Unclosed '{' in path pattern: ${path}`);
+            }
+            const name = path.substring(i + 1, end);
+            if (!name || !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+                throw new Error(`Invalid parameter name '${name}' in path '${path}'. Parameter names must be valid JavaScript identifiers (start with letter or underscore, contain only letters, digits, underscores).`);
+            }
+            if (BLOCKED_PARAM_NAMES.has(name)) {
+                throw new Error(`Parameter name '${name}' is reserved and cannot be used in path '${path}'.`);
+            }
+            paramNames.push(name);
+            regexStr += '([^/]+)';
+            i = end + 1;
+        }
+        else if (path[i] === '}') {
+            throw new Error(`Unexpected '}' without matching '{' in path pattern: ${path}`);
+        }
+        else if (path[i] === '*') {
+            wildcardCount++;
+            if (wildcardCount > 1) {
+                throw new Error(`Path '${path}' contains multiple wildcards. Only one wildcard (*) is allowed per route, and it must be the last segment.`);
+            }
+            if (i !== path.length - 1) {
+                throw new Error(`Path '${path}' contains multiple wildcards. Only one wildcard (*) is allowed per route, and it must be the last segment.`);
+            }
+            paramNames.push('*');
+            regexStr += '(.*)';
+            i++;
+        }
+        else if (REGEX_SPECIAL.has(path[i])) {
+            regexStr += '\\' + path[i];
+            i++;
+        }
+        else {
+            regexStr += path[i];
+            i++;
+        }
+    }
+    const fullPattern = '^' + regexStr + '$';
+    return { pattern: new RegExp(fullPattern), paramNames };
+}

package/dist/raw-route.mock.d.ts

@@ -0,0 +1,47 @@
+import { Scope } from './common/index.js';
+import type { ScopeParent } from './common/index.js';
+import { type RawRouteOptions } from './raw-route.js';
+export { RawRouteErrors, type RawRouteOptions, type HttpMethod } from './raw-route.js';
+/**
+ * Raw HTTP route Building Block.
+ *
+ * Provides raw HTTP endpoints with full request/response control, beyond the
+ * default RPC-only `POST /api` pattern. Routes are dispatched by the Lambda
+ * handler and dev server based on HTTP method + path pattern matching.
+ *
+ * ## Path
+ *
+ * When `path` is provided, it is used exactly as given. When omitted, the
+ * path is derived from the scope-chain IDs (excluding the root BlocksStack):
+ *
+ * ```typescript
+ * // Explicit path — used as-is
+ * new RawRoute(scope, 'health', { method: 'GET', path: '/health', handler });
+ *
+ * // Derived path — scope chain determines the URL
+ * new RawRoute(scope, 'health', { method: 'GET', handler });
+ * // If scope is the top-level Scope('my-app'), path becomes /health
+ * ```
+ *
+ * **Caution:** Changing the construct tree structure changes derived URLs.
+ * Use explicit paths for routes that must remain stable.
+ *
+ * ## Path syntax (when explicit)
+ *
+ * - `/health`       — exact match
+ * - `/users/{id}`   — named path parameter (captures one segment)
+ * - `/v1/*`         — wildcard (captures everything after prefix)
+ *
+ * ## How it works
+ *
+ * - At construction time, the route is registered in a global registry.
+ * - The Lambda handler and dev server check the registry before falling through to RPC dispatch.
+ * - The CDK side only validates the route (duplicate detection). No additional AWS resources
+ *   are created — the existing catch-all API Gateway proxy routes all paths to the Lambda.
+ */
+export declare class RawRoute extends Scope {
+    /** The resolved path this route is registered at. */
+    readonly path: string;
+    constructor(scope: ScopeParent, id: string, options: RawRouteOptions);
+}
+//# sourceMappingURL=raw-route.mock.d.ts.map

package/dist/raw-route.mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-route.mock.d.ts","sourceRoot":"","sources":["../src/raw-route.mock.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAmC,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEvF,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,qDAAqD;IACrD,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEjB,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe;CAKrE"}

package/dist/raw-route.mock.js

@@ -0,0 +1,51 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Scope } from './common/index.js';
+import { registerRoute, resolveRoutePath } from './raw-route.js';
+export { RawRouteErrors } from './raw-route.js';
+/**
+ * Raw HTTP route Building Block.
+ *
+ * Provides raw HTTP endpoints with full request/response control, beyond the
+ * default RPC-only `POST /api` pattern. Routes are dispatched by the Lambda
+ * handler and dev server based on HTTP method + path pattern matching.
+ *
+ * ## Path
+ *
+ * When `path` is provided, it is used exactly as given. When omitted, the
+ * path is derived from the scope-chain IDs (excluding the root BlocksStack):
+ *
+ * ```typescript
+ * // Explicit path — used as-is
+ * new RawRoute(scope, 'health', { method: 'GET', path: '/health', handler });
+ *
+ * // Derived path — scope chain determines the URL
+ * new RawRoute(scope, 'health', { method: 'GET', handler });
+ * // If scope is the top-level Scope('my-app'), path becomes /health
+ * ```
+ *
+ * **Caution:** Changing the construct tree structure changes derived URLs.
+ * Use explicit paths for routes that must remain stable.
+ *
+ * ## Path syntax (when explicit)
+ *
+ * - `/health`       — exact match
+ * - `/users/{id}`   — named path parameter (captures one segment)
+ * - `/v1/*`         — wildcard (captures everything after prefix)
+ *
+ * ## How it works
+ *
+ * - At construction time, the route is registered in a global registry.
+ * - The Lambda handler and dev server check the registry before falling through to RPC dispatch.
+ * - The CDK side only validates the route (duplicate detection). No additional AWS resources
+ *   are created — the existing catch-all API Gateway proxy routes all paths to the Lambda.
+ */
+export class RawRoute extends Scope {
+    /** The resolved path this route is registered at. */
+    path;
+    constructor(scope, id, options) {
+        super(id, { parent: scope });
+        this.path = resolveRoutePath(scope, id, options);
+        registerRoute({ ...options, path: this.path });
+    }
+}

package/dist/raw-route.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=raw-route.test.d.ts.map

package/dist/raw-route.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-route.test.d.ts","sourceRoot":"","sources":["../src/raw-route.test.ts"],"names":[],"mappings":""}