Add AICL example: 23_decorator_pipeline.aicl

data/aicl/examples/23_decorator_pipeline.aicl

@@ -0,0 +1,469 @@
+# AICL Example: Decorator Pattern Pipeline
+# Implements a decorator pattern pipeline for middleware chains, request/response filters,
+# and cross-cutting concerns like logging, authentication, rate limiting, caching, and compression.
+
+# Level 1: Architecture
+Goal: Build a decorator pattern pipeline that composes middleware chains for request processing,
+    applies request and response filters for cross-cutting concerns, supports ordering and
+    conditional activation of decorators, and enables transparent addition of behaviors without
+    modifying core business logic.
+
+Constraint: Each decorator must have a single responsibility and not mix concerns.
+Constraint: Decorator order must be explicitly declared; implicit ordering is forbidden.
+Constraint: A decorator must not swallow exceptions from inner handlers without re-raising or wrapping.
+Constraint: Pipeline must support both request and response decoration phases.
+Constraint: Each decorator must be independently testable without the full pipeline.
+
+Risk: Decorator order sensitivity causes subtle bugs
+Recovery: Document order dependencies; validate ordering constraints at pipeline construction time
+
+Risk: Exception in decorator leaves pipeline in partial state
+Recovery: Execute response decorators in reverse order on error path; ensure cleanup decorators run always
+
+Risk: Performance overhead from deep decorator nesting
+Recovery: Profile pipeline latency per decorator; collapse trivial decorators; add short-circuit option
+
+Risk: Decorator side effects leak between requests
+Recovery: Enforce per-request decorator state isolation; detect shared mutable state at registration
+
+Risk: Missing decorator causes silent feature gap
+Recovery: Declare required decorators per route; fail at startup if required decorator is missing
+
+Risk: Decorator configuration drift across environments
+Recovery: Version pipeline configurations; validate deployed configuration matches declared schema
+
+Layer: Pipeline
+    SubLayer: PipelineBuilder
+    SubLayer: PipelineExecutor
+    SubLayer: DecoratorChain
+Layer: Decorators
+    SubLayer: AuthenticationDecorator
+    SubLayer: RateLimitDecorator
+    SubLayer: LoggingDecorator
+    SubLayer: CachingDecorator
+    SubLayer: CompressionDecorator
+Layer: Core
+    SubLayer: RequestHandler
+    SubLayer: ResponseProcessor
+    SubLayer: ErrorHandler
+
+Validation: Each decorator must implement before and after hooks
+Validation: Pipeline must contain at least one terminal handler
+Validation: Decorator ordering must satisfy declared dependency constraints
+Validation: No decorator may modify the request object in place; must return new instance
+Validation: Pipeline execution time must not exceed configured maximum
+Validation: Error handler decorator must be present in every pipeline
+
+# Level 2: Entities
+Entity Pipeline
+    pipelineId: string
+    name: string
+    decorators: list
+    terminalHandler: string
+    maxExecutionTime: integer
+    createdAt: datetime
+    version: string
+    isActive: boolean
+
+Entity Decorator
+    decoratorId: string
+    decoratorName: string
+    decoratorType: string
+    order: integer
+    isRequired: boolean
+    config: dict
+    isActive: boolean
+    appliesTo: list
+    dependencies: list
+
+Entity RequestContext
+    requestId: string
+    method: string
+    path: string
+    headers: dict
+    body: any
+    queryParams: dict
+    attributes: dict
+    startTime: datetime
+    userId: string
+
+Entity ResponseContext
+    requestId: string
+    statusCode: integer
+    headers: dict
+    body: any
+    attributes: dict
+    processingTime: integer
+    decoratorTrail: list
+    cacheHit: boolean
+
+Entity DecoratorResult
+    decoratorId: string
+    phase: string
+    duration: integer
+    modified: boolean
+    shortCircuited: boolean
+    error: string
+    timestamp: datetime
+
+Entity PipelineExecution
+    executionId: string
+    pipelineId: string
+    requestId: string
+    startedAt: datetime
+    completedAt: datetime
+    totalDuration: integer
+    decoratorResults: list
+    finalStatus: string
+    errorDecorator: string
+
+# Level 3: Behaviors
+Behavior BuildPipeline
+    Input:
+        name: string
+        decoratorConfigs: list
+        terminalHandler: string
+    Output:
+        pipelineId: string
+    Action:
+        Validate all decorator configurations
+        Resolve decorator dependencies and validate availability
+        Sort decorators by declared order with dependency resolution
+        Check for circular dependencies between decorators
+        Validate terminal handler exists
+        Register pipeline with version stamp
+        Return pipeline identifier
+
+Behavior ExecutePipeline
+    Input:
+        pipeline: Pipeline
+        request: RequestContext
+    Output:
+        response: ResponseContext
+    Action:
+        Initialize execution tracking
+        Execute request phase of each decorator in order
+        If any decorator short-circuits, skip remaining request decorators
+        Invoke terminal handler with decorated request
+        Execute response phase of each decorator in reverse order
+        Handle errors by delegating to error handler decorator
+        Collect timing and modification data from each decorator
+        Return final decorated response
+
+Behavior ApplyDecorator
+    Input:
+        decorator: Decorator
+        context: any
+        phase: string
+    Output:
+        result: DecoratorResult
+        modifiedContext: any
+    Action:
+        Check decorator activation condition against context
+        If inactive, pass through without modification
+        Execute decorator logic for specified phase
+        Track whether context was modified
+        Handle decorator-specific errors gracefully
+        Return decorator result and modified context
+
+Behavior ShortCircuit
+    Input:
+        decorator: Decorator
+        response: ResponseContext
+        reason: string
+    Output:
+        response: ResponseContext
+    Action:
+        Set short-circuit flag on decorator result
+        Skip remaining request-phase decorators
+        Begin response phase from short-circuit point
+        Add short-circuit reason to response attributes
+        Return immediate response
+
+Behavior HandlePipelineError
+    Input:
+        pipeline: Pipeline
+        failedDecorator: string
+        error: string
+        request: RequestContext
+    Output:
+        errorResponse: ResponseContext
+    Action:
+        Log error with full decorator trail
+        Execute cleanup phase for decorators that ran before failure
+        Apply error handler decorator to produce user-facing response
+        Record error in pipeline execution metrics
+        Ensure no decorator state leaks to error response
+        Return sanitized error response
+
+Behavior ComposeDecorators
+    Input:
+        first: Decorator
+        second: Decorator
+    Output:
+        composed: Decorator
+    Action:
+        Merge configuration of both decorators
+        Compose before-hook as second then first
+        Compose after-hook as first then second
+        Resolve order conflicts with priority rule
+        Register composed decorator with merged metadata
+        Return composed decorator reference
+
+# Level 4: Conditions
+Condition: RateLimitExceeded
+    When rate limit decorator detects request count exceeds threshold
+    Then short-circuit with HTTP 429 and include retry-after header
+
+Condition: AuthenticationFailed
+    When authentication decorator cannot validate credentials
+    Then short-circuit with HTTP 401 and terminate pipeline without reaching handler
+
+Condition: CacheHitOnRead
+    When caching decorator finds valid cached response for request
+    Then short-circuit with cached response; skip terminal handler entirely
+
+# Level 5: Events
+Event: OnPipelineBuilt
+    On new pipeline assembled and validated
+    Action: Log pipeline composition, warm decorator instances, verify all dependencies met
+
+Event: OnDecoratorShortCircuit
+    On decorator triggers short-circuit during request phase
+    Action: Record which decorator short-circuited and why; update pipeline metrics
+
+Event: OnPipelineError
+    On unhandled exception during pipeline execution
+    Action: Alert on-call, increment error metric, preserve request context for debugging
+
+Event: OnDecoratorAdded
+    On new decorator registered in the system
+    Action: Validate decorator contract compliance, add to decorator catalog, test in isolation
+
+# Level 6: Concurrency
+Parallel:
+    Independent pipeline executions for different requests
+    Decorator activation condition evaluation
+    Caching decorator lookup against distributed cache
+    Rate limit counter updates with atomic increments
+    Pipeline metric aggregation from all execution threads
+
+# Level 7: Optimization
+Optimize: Pipeline execution latency
+    Priority: Short-circuit expensive decorators early; cache decorator activation evaluation results
+
+Optimize: Decorator instantiation overhead
+    Priority: Pool decorator instances; reuse across requests; lazy-initialize expensive resources
+
+# Level 8: Learning
+Learn: Optimal decorator ordering
+    Goal: Minimize average pipeline latency by reordering decorators based on short-circuit frequency
+    Adapt: Decorator order within dependency constraints
+    Based: Short-circuit rate per decorator and cost of executing each decorator
+
+Learn: Cache effectiveness per route
+    Goal: Maximize cache hit ratio while minimizing memory usage
+    Adapt: Caching decorator TTL and cacheable routes per method-path pattern
+    Based: Cache hit ratio, response size, and request frequency per route
+
+# Level 9: Security
+Security:
+    Encrypt: Request bodies containing sensitive data as they pass through decorator pipeline
+    Encrypt: Decorator configuration secrets using vault-backed encrypted config
+    Protect: Authentication decorator tokens with short-lived JWT and rotation
+    Protect: Rate limit state from manipulation via signed counters stored in secure backend
+    Protect: Pipeline from decorator injection by validating decorator signatures at registration
+
+# Level 10: Native
+TypeScript
+{
+type RequestPhase = 'before' | 'after';
+type Next = () => Promise<ResponseContext>;
+
+interface RequestContext {
+    requestId: string;
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    body: any;
+    queryParams: Record<string, string>;
+    attributes: Record<string, any>;
+    startTime: Date;
+    userId?: string;
+}
+
+interface ResponseContext {
+    requestId: string;
+    statusCode: number;
+    headers: Record<string, string>;
+    body: any;
+    attributes: Record<string, any>;
+    processingTime: number;
+    decoratorTrail: string[];
+    cacheHit: boolean;
+}
+
+interface Decorator {
+    name: string;
+    order: number;
+    before?: (req: RequestContext, next: Next) => Promise<ResponseContext>;
+    after?: (req: RequestContext, res: ResponseContext) => Promise<ResponseContext>;
+    isActive: (req: RequestContext) => boolean;
+}
+
+class Pipeline {
+    private decorators: Decorator[] = [];
+    private terminalHandler: (req: RequestContext) => Promise<ResponseContext>;
+
+    constructor(terminalHandler: (req: RequestContext) => Promise<ResponseContext>) {
+        this.terminalHandler = terminalHandler;
+    }
+
+    use(decorator: Decorator): Pipeline {
+        this.decorators.push(decorator);
+        this.decorators.sort((a, b) => a.order - b.order);
+        return this;
+    }
+
+    async execute(request: RequestContext): Promise<ResponseContext> {
+        const trail: string[] = [];
+        const startTime = Date.now();
+
+        const buildChain = (index: number): Next => {
+            return async (): Promise<ResponseContext> => {
+                if (index >= this.decorators.length) {
+                    const response = await this.terminalHandler(request);
+                    return {
+                        requestId: request.requestId,
+                        statusCode: response.statusCode,
+                        headers: response.headers,
+                        body: response.body,
+                        attributes: {},
+                        processingTime: Date.now() - startTime,
+                        decoratorTrail: trail,
+                        cacheHit: false,
+                    };
+                }
+
+                const decorator = this.decorators[index];
+                if (!decorator.isActive(request)) {
+                    return buildChain(index + 1)();
+                }
+
+                trail.push(decorator.name);
+
+                if (decorator.before) {
+                    return decorator.before(request, buildChain(index + 1));
+                }
+                return buildChain(index + 1)();
+            };
+        };
+
+        let response = await buildChain(0)();
+
+        for (let i = this.decorators.length - 1; i >= 0; i--) {
+            const decorator = this.decorators[i];
+            if (decorator.after && decorator.isActive(request)) {
+                response = await decorator.after(request, response);
+            }
+        }
+
+        return response;
+    }
+}
+
+const loggingDecorator: Decorator = {
+    name: 'logging',
+    order: 0,
+    before: async (req, next) => {
+        console.log(`[${req.requestId}] --> ${req.method} ${req.path}`);
+        const res = await next();
+        console.log(`[${req.requestId}] <-- ${res.statusCode}`);
+        return res;
+    },
+    isActive: () => true,
+};
+
+const authDecorator: Decorator = {
+    name: 'authentication',
+    order: 10,
+    before: async (req, next) => {
+        const token = req.headers['authorization'];
+        if (!token) {
+            return {
+                requestId: req.requestId,
+                statusCode: 401,
+                headers: {},
+                body: { error: 'Unauthorized' },
+                attributes: {},
+                processingTime: 0,
+                decoratorTrail: [],
+                cacheHit: false,
+            };
+        }
+        req.userId = token.replace('Bearer ', '');
+        return next();
+    },
+    isActive: (req) => !req.path.startsWith('/public'),
+};
+
+const rateLimitDecorator: Decorator = {
+    name: 'rate-limit',
+    order: 5,
+    before: async (req, next) => {
+        const count = rateLimitCounter.increment(req.attributes['clientIp'] as string);
+        if (count > 100) {
+            return {
+                requestId: req.requestId,
+                statusCode: 429,
+                headers: { 'retry-after': '60' },
+                body: { error: 'Rate limit exceeded' },
+                attributes: {},
+                processingTime: 0,
+                decoratorTrail: [],
+                cacheHit: false,
+            };
+        }
+        return next();
+    },
+    isActive: () => true,
+};
+
+class RateLimitCounter {
+    private counts = new Map<string, number>();
+    increment(key: string): number {
+        const current = (this.counts.get(key) || 0) + 1;
+        this.counts.set(key, current);
+        return current;
+    }
+}
+
+const rateLimitCounter = new RateLimitCounter();
+
+async function handler(req: RequestContext): Promise<ResponseContext> {
+    return {
+        requestId: req.requestId,
+        statusCode: 200,
+        headers: { 'content-type': 'application/json' },
+        body: { message: 'Hello', userId: req.userId },
+        attributes: {},
+        processingTime: 0,
+        decoratorTrail: [],
+        cacheHit: false,
+    };
+}
+
+const pipeline = new Pipeline(handler)
+    .use(loggingDecorator)
+    .use(rateLimitDecorator)
+    .use(authDecorator);
+
+const req: RequestContext = {
+    requestId: 'req-1', method: 'GET', path: '/api/data',
+    headers: { authorization: 'Bearer user-123' },
+    body: null, queryParams: {}, attributes: { clientIp: '10.0.0.1' },
+    startTime: new Date(),
+};
+
+pipeline.execute(req).then(res => console.log('Response:', res.statusCode, res.body));
+}