serverless-ircd 0.7.0 → 0.8.0

package/apps/aws-stack/src/aws-stack.ts

@@ -16,9 +16,18 @@
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { TABLE_DEFS } from '@serverless-ircd/aws-adapter/cdk-table-defs';
-import { CfnOutput, Duration, RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib';
+import {
+  CfnOutput,
+  CfnParameter,
+  Duration,
+  RemovalPolicy,
+  Stack,
+  type StackProps,
+} from 'aws-cdk-lib';
+import { CfnAccount } from 'aws-cdk-lib/aws-apigateway';
 import {
   CfnIntegrationResponse,
+  type CfnStage,
   WebSocketApi,
   type WebSocketIntegration,
   WebSocketStage,
@@ -37,8 +46,10 @@ import {
 import { LambdaTarget } from 'aws-cdk-lib/aws-elasticloadbalancingv2-targets';
 import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
 import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
+import { PolicyStatement, Role, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
 import { Code, Function as Lambda, Runtime } from 'aws-cdk-lib/aws-lambda';
 import { NodejsFunction, type NodejsFunctionProps } from 'aws-cdk-lib/aws-lambda-nodejs';
+import { LogGroup, RetentionDays } from 'aws-cdk-lib/aws-logs';
 import type { Construct } from 'constructs';
 
 /** Stage name served by the auto-deploying WebSocket stage. */
@@ -154,10 +165,79 @@ export class IrcAwsStack extends Stack {
     super(scope, id, props);
 
     const environmentName = props.environmentName ?? DEFAULT_ENVIRONMENT_NAME;
-    const serverName = props.serverName ?? DEFAULT_SERVER_NAME;
-    const networkName = props.networkName ?? DEFAULT_NETWORK_NAME;
+
+    // Server identity is exposed as CloudFormation Parameters so it can be
+    // overridden at deploy time (`cdk deploy --parameters ServerName=...`,
+    // `aws cloudformation update-stack --parameters`, or the CFN console)
+    // without re-synth. The construct prop (and the `bin/aws.ts` context
+    // var) flow into the parameter `Default`; a `--parameters` override at
+    // deploy time wins over the default. Lambdas consume the value via
+    // `{ Ref: ... }` so an update rolls the env vars with no code change.
+    const serverNameParam = new CfnParameter(this, 'ServerName', {
+      type: 'String',
+      description:
+        "Server name advertised to IRC clients (the `001` welcome source, ISUPPORT's SERVER_NAME). " +
+        'Override at deploy time via `--parameters ServerName=...`.',
+      default: props.serverName ?? DEFAULT_SERVER_NAME,
+    });
+    const networkNameParam = new CfnParameter(this, 'NetworkName', {
+      type: 'String',
+      description:
+        'Network name advertised to IRC clients in ISUPPORT (`NETWORK`). ' +
+        'Override at deploy time via `--parameters NetworkName=...`.',
+      default: props.networkName ?? DEFAULT_NETWORK_NAME,
+    });
+    const serverName = serverNameParam.valueAsString;
+    const networkName = networkNameParam.valueAsString;
+
+    // Execution logging for the WebSocket API. INFO enables full
+    // request/response tracing (verbose — use for debugging connect/drop
+    // issues); ERROR logs only server-side failures; OFF disables. The
+    // level is a CFN parameter so it can be flipped at deploy time without
+    // a code change: `cdk deploy --parameters ApiGatewayLoggingLevel=OFF`.
+    // NB: execution logging also needs the account-level CloudWatch role,
+    // provisioned below (`ApiGatewayAccount`); that resource is GLOBAL per
+    // account+region, so two stacks with logging ON in the same
+    // account+region will conflict — deploy each env in its own account or
+    // set this to OFF.
+    const apiLoggingLevelParam = new CfnParameter(this, 'ApiGatewayLoggingLevel', {
+      type: 'String',
+      description:
+        'API Gateway WebSocket execution logging level. INFO = full request/response tracing ' +
+        '(verbose, for debugging); ERROR = 5xx only; OFF = disabled. Requires the account ' +
+        'CloudWatch role (auto-provisioned; global per account+region).',
+      default: 'INFO',
+      allowedValues: ['OFF', 'INFO', 'ERROR'],
+    });
     const motd = (props.motdLines ?? DEFAULT_MOTD_LINES).join('\n');
 
+    // EventBridge schedule expressions are surfaced as CloudFormation
+    // Parameters for the same reason as server identity: they can be
+    // overridden at deploy time (`--parameters SweeperScheduleExpression=...`)
+    // without a re-synth. The defaults are derived from the same
+    // `Schedule.rate(Duration)` calls used previously so the produced
+    // strings (`rate(5 minutes)`, `rate(1 minute)` — including the
+    // singular/plural handling) are byte-identical to the old behaviour.
+    // Validation moves from synth (Duration bounds) to deploy time: an
+    // invalid expression (`rate(0 minutes)`, a malformed `cron(...)`)
+    // fails the `AWS::Events::Rule` create with an EventBridge error.
+    const sweeperScheduleParam = new CfnParameter(this, 'SweeperScheduleExpression', {
+      type: 'String',
+      description:
+        'EventBridge schedule expression for the gone-connection sweeper ' +
+        '(`rate(5 minutes)` or a `cron(...)` expression). Override at deploy ' +
+        'time via `--parameters SweeperScheduleExpression=...`.',
+      default: Schedule.rate(SWEEPER_SCHEDULE_RATE).expressionString,
+    });
+    const pingCheckerScheduleParam = new CfnParameter(this, 'PingCheckerScheduleExpression', {
+      type: 'String',
+      description:
+        'EventBridge schedule expression for the idle / PING checker ' +
+        '(`rate(1 minute)` or a `cron(...)` expression). Override at deploy ' +
+        'time via `--parameters PingCheckerScheduleExpression=...`.',
+      default: Schedule.rate(PING_CHECKER_SCHEDULE_RATE).expressionString,
+    });
+
     // Prefix every physical table name with the environment so parallel
     // envs (staging + production) cannot collide in one account+region.
     // The first letter is capitalised to compose cleanly with the
@@ -248,7 +328,7 @@ export class IrcAwsStack extends Stack {
       integrationId: connectIntegration.integrationId,
       integrationResponseKey: '$default',
       responseParameters: {
-        'method.response.header.Sec-WebSocket-Protocol':
+        'route.response.header.Sec-WebSocket-Protocol':
           'integration.response.header.Sec-WebSocket-Protocol',
       },
     });
@@ -258,11 +338,90 @@ export class IrcAwsStack extends Stack {
     // own WebSocket API), so `prod` in every env resolves to a distinct
     // endpoint. Keeping a fixed stage keeps client connect URLs stable
     // and identical in shape across environments.
+    // CloudWatch LogGroup + IAM role for API Gateway access + execution
+    // logging. Execution logging (full request/response at INFO) is what
+    // makes APIGW-side frame drops diagnosable — the Lambda logs alone
+    // can't show a frame that never reached the handler.
+    const apiLogGroup = new LogGroup(this, 'ApiGatewayAccessLogs', {
+      retention: RetentionDays.TWO_WEEKS,
+      removalPolicy: RemovalPolicy.DESTROY,
+    });
+    const apiLoggingRole = new Role(this, 'ApiGatewayLoggingRole', {
+      assumedBy: new ServicePrincipal('apigateway.amazonaws.com'),
+    });
+    // APIGW validates this role when it is set as the account CloudWatch
+    // role, and rejects one scoped to a single log-group ARN: execution
+    // logs land in APIGW's OWN log groups (AWS/ApiGateway...), separate
+    // from this stack's access-log group. Grant the logs write actions
+    // across all log groups. Defined inline (not via the
+    // AmazonAPIGatewayPushToCloudWatchLogs managed policy) because that
+    // managed policy is not available in every partition.
+    apiLoggingRole.addToPolicy(
+      new PolicyStatement({
+        actions: [
+          'logs:CreateLogGroup',
+          'logs:CreateLogStream',
+          'logs:DescribeLogGroups',
+          'logs:DescribeLogStreams',
+          'logs:PutLogEvents',
+        ],
+        resources: ['*'],
+      }),
+    );
+    // Account-level CloudWatch role for API Gateway. GLOBAL per
+    // account+region (see ApiGatewayLoggingLevel caveat above): two stacks
+    // in the same account+region both defining this resource will conflict.
+    const apiAccount = new CfnAccount(this, 'ApiGatewayAccount', {
+      cloudWatchRoleArn: apiLoggingRole.roleArn,
+    });
+    // APIGW validates the role's CONTENT — trust AND the attached
+    // permissions — when it processes the AWS::ApiGateway::Account
+    // resource. `addToPolicy` renders as a SEPARATE AWS::IAM::Policy, and
+    // the Account only references the role Arn, so CloudFormation can apply
+    // the Account after the Role is created but BEFORE the policy attaches.
+    // APIGW then assumes a permission-less role and rejects the update:
+    //   "The role ARN does not have required permissions configured."
+    // The explicit dependency forces the policy to be applied first.
+    const loggingRolePolicy = apiLoggingRole.node.findChild('DefaultPolicy');
+    apiAccount.node.addDependency(loggingRolePolicy);
+
     const stage = new WebSocketStage(this, 'Stage', {
       webSocketApi,
       stageName: STAGE_NAME,
       autoDeploy: true,
     });
+    const cfnStage = stage.node.defaultChild as CfnStage;
+    // The Stage's logging config requires the account-wide CloudWatch role
+    // to exist first; without this explicit dependency CloudFormation can
+    // apply the Stage before the Account resource and APIGW rejects the
+    // update: "CloudWatch Logs role ARN must be set in account settings".
+    cfnStage.addResourceDependency(apiAccount);
+    // Access + execution logging on the stage. Set at the L1 (CfnStage)
+    // level because the L2 `accessLogSettings.format` expects an ILogFormat
+    // object; the raw CFN `AccessLogSettings.Format` is a plain string.
+    // Access log: one line per request — enough to correlate a connect /
+    // frame with a connectionId without the verbosity of execution logs.
+    cfnStage.accessLogSettings = {
+      destinationArn: apiLogGroup.logGroupArn,
+      format: JSON.stringify({
+        requestId: '$context.requestId',
+        routeKey: '$context.routeKey',
+        eventType: '$context.eventType',
+        connectionId: '$context.connectionId',
+        status: '$context.status',
+        responseLength: '$context.responseLength',
+        requestTime: '$context.requestTime',
+        sourceIp: '$context.sourceIp',
+      }),
+    };
+    // Execution logging: the parameter drives LoggingLevel (OFF/INFO/ERROR);
+    // DataTraceEnabled logs full request/response bodies when a level is
+    // active. This is the layer that shows whether APIGW received and routed
+    // a client frame or dropped it pre-Lambda.
+    cfnStage.defaultRouteSettings = {
+      loggingLevel: apiLoggingLevelParam.valueAsString,
+      dataTraceEnabled: true,
+    };
 
     stage.grantManagementApiAccess(handler);
     stage.grantManagementApiAccess(pingChecker);
@@ -283,31 +442,40 @@ export class IrcAwsStack extends Stack {
       pingChecker.addEnvironment(envName, physicalName);
     }
 
-    // Server identity (consumed by the handler's config loader). Sourced
-    // from the single prop bag and injected into BOTH the handler and the
-    // ping checker — the ping checker needs SERVER_NAME / NETWORK_NAME /
-    // MOTD to build the same server-shaped config via the shared loader.
-    // The sweeper does not. MOTD is `\n`-joined so `buildLambdaConfigInput`
-    // splits it back into the expected `motdLines` array.
+    // Server identity is injected into the handler, ping checker, AND the
+    // sweeper. All three share `buildDepsFromEnv` at cold start, which calls
+    // `loadServerConfigFromLambdaEnv` — and that loader hard-requires
+    // SERVER_NAME / NETWORK_NAME (and reads MOTD). Omitting them on the
+    // sweeper made every scheduled invocation throw "serverName: Required".
+    // Values flow through the CloudFormation parameters ({ Ref }) so a
+    // `--parameters` update rolls all four Lambdas with no code change.
+    // MOTD is `\n`-joined so `buildLambdaConfigInput` splits it back into
+    // the expected `motdLines` array.
     handler.addEnvironment('SERVER_NAME', serverName);
     handler.addEnvironment('NETWORK_NAME', networkName);
     handler.addEnvironment('MOTD', motd);
     pingChecker.addEnvironment('SERVER_NAME', serverName);
     pingChecker.addEnvironment('NETWORK_NAME', networkName);
     pingChecker.addEnvironment('MOTD', motd);
-
-    // EventBridge schedule → sweeper Lambda. Fixed rate per the architecture
-    // doc; the sweeper is self-throttling (Scans + per-row cleanupConnection).
+    sweeper.addEnvironment('SERVER_NAME', serverName);
+    sweeper.addEnvironment('NETWORK_NAME', networkName);
+    sweeper.addEnvironment('MOTD', motd);
+
+    // EventBridge schedule → sweeper Lambda. The schedule expression comes
+    // from a CloudFormation Parameter (see above), so it can be overridden
+    // at deploy time; the sweeper is self-throttling
+    // (Scans + per-row cleanupConnection).
     new Rule(this, 'SweeperSchedule', {
-      schedule: Schedule.rate(SWEEPER_SCHEDULE_RATE),
+      schedule: Schedule.expression(sweeperScheduleParam.valueAsString),
       targets: [new LambdaFunction(sweeper)],
     });
 
-    // EventBridge schedule → idle / PING checker Lambda. Fixed rate(1 minute)
-    // so an idle connection sees its first PING within one tick of the
-    // configured `DEFAULT_PING_INTERVAL_MS` (60 s).
+    // EventBridge schedule → idle / PING checker Lambda. Schedule expression
+    // is a deploy-time Parameter; the default (`rate(1 minute)`) means an
+    // idle connection sees its first PING within one tick of the configured
+    // `DEFAULT_PING_INTERVAL_MS` (60 s).
     new Rule(this, 'PingCheckerSchedule', {
-      schedule: Schedule.rate(PING_CHECKER_SCHEDULE_RATE),
+      schedule: Schedule.expression(pingCheckerScheduleParam.valueAsString),
       targets: [new LambdaFunction(pingChecker)],
     });