stacktape 3.5.8 → 3.6.0-beta.0

package/ai-docs/config-ref/solidstart-web.md

@@ -0,0 +1,75 @@
+---
+docType: config-ref
+title: Solid Start Web
+resourceType: solidstart-web
+tags:
+  - solidstart-web
+  - solidstart
+  - solid
+source: types/stacktape-config/solidstart-web.d.ts
+priority: 1
+---
+
+# Solid Start Web
+
+Deploy a SolidStart SSR app with Lambda (AWS adapter), S3 for static assets, and CloudFront CDN.
+
+Resource type: `solidstart-web`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Deploy a SolidStart SSR app with Lambda (AWS adapter), S3 for static assets, and CloudFront CDN.
+ */
+interface SolidStartWeb {
+  type: 'solidstart-web';
+  properties: SolidStartWebProps;
+  overrides?: ResourceOverrides;
+}
+
+interface SolidStartWebProps extends ResourceAccessProps {
+  /**
+   * #### Directory containing your `app.config.ts`. For monorepos, point to the SolidStart workspace.
+   *
+   * @default "."
+   */
+  appDirectory?: string;
+  /**
+   * #### Override the default `vinxi build` command.
+   */
+  buildCommand?: string;
+  /**
+   * #### Environment variables for the SSR function. Use `$ResourceParam()` or `$Secret()` for dynamic values.
+   */
+  environment?: EnvironmentVar[];
+  /**
+   * #### Attach custom domains with auto-managed DNS records and TLS certificates.
+   *
+   * ---
+   *
+   * **Prerequisite:** A Route 53 hosted zone for your domain must exist in your AWS account.
+   */
+  customDomains?: DomainConfiguration[];
+  /**
+   * #### Customize the SSR Lambda function (memory, timeout, VPC, logging).
+   */
+  serverLambda?: SsrWebServerLambdaConfig;
+  /**
+   * #### Name of a `web-app-firewall` resource to protect this app. Firewall `scope` must be `cdn`.
+   */
+  useFirewall?: string;
+  /**
+   * #### Dev server config for `stacktape dev`. Defaults to `vinxi dev`.
+   */
+  dev?: SsrWebDevConfig;
+  /**
+   * #### Set custom headers (e.g., `Cache-Control`) for static files matching a pattern.
+   */
+  fileOptions?: DirectoryUploadFilter[];
+  /**
+   * #### CDN cache controls for SSR routes and specific path patterns.
+   */
+  cdn?: SsrWebCdnConfig;
+}
+```

package/ai-docs/config-ref/sqs-queue-not-empty.md

@@ -0,0 +1,405 @@
+---
+docType: config-ref
+title: Alarm Definition Base
+resourceType: sqs-queue-not-empty
+tags:
+  - sqs-queue-not-empty
+source: types/stacktape-config/alarms.d.ts
+priority: 1
+---
+
+# Alarm Definition Base
+
+Resource type: `sqs-queue-not-empty`
+
+## TypeScript Definition
+
+```typescript
+type AlarmUserIntegration = MsTeamsIntegration | SlackIntegration | EmailIntegration;
+
+interface AlarmDefinitionBase {
+  /**
+   * #### How long and how often to evaluate the metric before triggering.
+   *
+   * ---
+   *
+   * Controls the evaluation window (period), how many periods to look at, and how many must breach
+   * the threshold to fire the alarm. Useful for filtering out short spikes.
+   */
+  evaluation?: AlarmEvaluation;
+  /**
+   * #### Where to send notifications when the alarm fires — Slack, MS Teams, or email.
+   */
+  notificationTargets?: AlarmUserIntegration[];
+  /**
+   * #### Custom alarm description used in notification messages and the AWS console.
+   */
+  description?: string;
+}
+
+interface AlarmDefinition extends AlarmDefinitionBase {
+  /**
+   * #### A unique name for this alarm (e.g., `api-error-rate`, `db-cpu-high`).
+   */
+  name: string;
+  /**
+   * #### The metric and threshold that fires this alarm.
+   *
+   * ---
+   *
+   * `type` selects what to monitor (error rate, CPU, latency, etc.) and `properties` set the threshold.
+   */
+  trigger: AlarmTrigger;
+  /**
+   * #### Only activate this alarm for these services. If omitted, applies to all services.
+   */
+  forServices?: string[];
+  /**
+   * #### Only activate this alarm for these stages (e.g., `production`). If omitted, applies to all stages.
+   */
+  forStages?: string[];
+}
+
+interface StpAlarm extends AlarmDefinition {
+  nameChain: string[];
+}
+
+interface ApplicationLoadBalancerAlarm extends AlarmDefinitionBase {
+  trigger: ApplicationLoadBalancerAlarmTrigger;
+}
+
+interface HttpApiGatewayAlarm extends AlarmDefinitionBase {
+  trigger: HttpApiGatewayAlarmTrigger;
+}
+
+interface LambdaAlarm extends AlarmDefinitionBase {
+  trigger: LambdaAlarmTrigger;
+}
+
+interface RelationalDatabaseAlarm extends AlarmDefinitionBase {
+  trigger: RelationalDatabaseAlarmTrigger;
+}
+
+interface SqsQueueAlarm extends AlarmDefinitionBase {
+  trigger: SqsQueueAlarmTrigger;
+}
+
+type ApplicationLoadBalancerAlarmTrigger =
+  | ApplicationLoadBalancerErrorRateTrigger
+  | ApplicationLoadBalancerUnhealthyTargetsTrigger
+  | ApplicationLoadBalancerCustomTrigger;
+type SqsQueueAlarmTrigger = SqsQueueReceivedMessagesCountTrigger | SqsQueueNotEmptyTrigger;
+type LambdaAlarmTrigger = LambdaErrorRateTrigger | LambdaDurationTrigger;
+type HttpApiGatewayAlarmTrigger = HttpApiGatewayErrorRateTrigger | HttpApiGatewayLatencyTrigger;
+type RelationalDatabaseAlarmTrigger =
+  | RelationalDatabaseReadLatencyTrigger
+  | RelationalDatabaseWriteLatencyTrigger
+  | RelationalDatabaseCPUUtilizationTrigger
+  | RelationalDatabaseFreeStorageTrigger
+  | RelationalDatabaseFreeMemoryTrigger
+  | RelationalDatabaseConnectionCountTrigger;
+
+type AlarmTrigger =
+  | LambdaErrorRateTrigger
+  | LambdaDurationTrigger
+  | RelationalDatabaseReadLatencyTrigger
+  | RelationalDatabaseWriteLatencyTrigger
+  | RelationalDatabaseCPUUtilizationTrigger
+  | RelationalDatabaseFreeStorageTrigger
+  | RelationalDatabaseFreeMemoryTrigger
+  | RelationalDatabaseConnectionCountTrigger
+  | HttpApiGatewayErrorRateTrigger
+  | HttpApiGatewayLatencyTrigger
+  | ApplicationLoadBalancerErrorRateTrigger
+  | ApplicationLoadBalancerUnhealthyTargetsTrigger
+  | ApplicationLoadBalancerCustomTrigger
+  | SqsQueueReceivedMessagesCountTrigger
+  | SqsQueueNotEmptyTrigger;
+
+type AlarmTriggerType = AlarmTrigger['type'];
+
+interface AlarmEvaluation {
+  /**
+   * #### Duration of one evaluation period in seconds. Must be a multiple of 60.
+   *
+   * @default 60
+   */
+  period?: number;
+  /**
+   * #### How many recent periods to evaluate. Prevents alarms from firing on short spikes.
+   *
+   * ---
+   *
+   * Example: set to `5` with `breachedPeriods: 3` — the alarm fires only if the threshold is breached
+   * in at least 3 of the last 5 periods.
+   *
+   * @default 1
+   */
+  evaluationPeriods?: number;
+  /**
+   * #### How many periods (within `evaluationPeriods`) must breach the threshold to fire the alarm.
+   *
+   * ---
+   *
+   * Must be ≤ `evaluationPeriods`.
+   *
+   * @default 1
+   */
+  breachedPeriods?: number;
+}
+
+interface SqsQueueNotEmptyTrigger {
+  /**
+   * #### Fires when the SQS queue has unprocessed messages.
+   *
+   * ---
+   *
+   * The queue is considered "not empty" if any of these are non-zero: visible messages,
+   * in-flight messages, messages received, or messages sent.
+   */
+  type: 'sqs-queue-not-empty';
+}
+
+interface SqsQueueReceivedMessagesCountTrigger {
+  type: 'sqs-queue-received-messages-count';
+  properties: SqsQueueReceivedMessagesCountTriggerProps;
+}
+
+interface SqsQueueReceivedMessagesCountTriggerProps extends TriggerWithCustomComparison, TriggerWithCustomStatFunction {
+  /**
+   * #### Fires when received message count crosses this threshold.
+   *
+   * ---
+   *
+   * Default: fires if **average** messages received per period > `thresholdCount`.
+   * Customize with `statistic` and `comparisonOperator`.
+   */
+  thresholdCount: number;
+}
+
+interface ApplicationLoadBalancerErrorRateTrigger {
+  type: 'application-load-balancer-error-rate';
+  properties: ApplicationLoadBalancerErrorRateTriggerProps;
+}
+
+interface ApplicationLoadBalancerErrorRateTriggerProps extends TriggerWithCustomComparison {
+  /**
+   * #### Fires when 4xx/5xx error rate exceeds this percentage.
+   *
+   * ---
+   *
+   * Example: `5` fires the alarm if more than 5% of requests return errors.
+   */
+  thresholdPercent: number;
+}
+
+interface ApplicationLoadBalancerUnhealthyTargetsTrigger {
+  type: 'application-load-balancer-unhealthy-targets';
+  properties: ApplicationLoadBalancerUnhealthyTargetsTriggerProps;
+}
+
+interface ApplicationLoadBalancerUnhealthyTargetsTriggerProps extends TriggerWithCustomComparison {
+  /**
+   * #### Fires when the percentage of unhealthy targets exceeds this value.
+   *
+   * ---
+   *
+   * If the load balancer has multiple target groups, the alarm fires if *any* group breaches the threshold.
+   */
+  thresholdPercent: number;
+  /**
+   * #### Only monitor health of these target container services. If omitted, monitors all targets.
+   *
+   * ---
+   *
+   * Only services actually targeted by the load balancer can be listed.
+   */
+  onlyIncludeTargets?: string[];
+}
+
+interface HttpApiGatewayErrorRateTrigger {
+  type: 'http-api-gateway-error-rate';
+  properties: HttpApiGatewayErrorRateTriggerProps;
+}
+
+interface HttpApiGatewayErrorRateTriggerProps extends TriggerWithCustomComparison {
+  /**
+   * #### Fires when 4xx/5xx error rate exceeds this percentage.
+   */
+  thresholdPercent: number;
+}
+
+interface HttpApiGatewayLatencyTrigger {
+  type: 'http-api-gateway-latency';
+  properties: HttpApiGatewayLatencyTriggerProps;
+}
+
+interface HttpApiGatewayLatencyTriggerProps extends TriggerWithCustomComparison, TriggerWithCustomStatFunction {
+  /**
+   * #### Fires when request-to-response latency exceeds this value (ms).
+   *
+   * ---
+   *
+   * Default: fires if **average** latency > threshold. Customize with `statistic` and `comparisonOperator`.
+   */
+  thresholdMilliseconds: number;
+}
+
+interface LambdaErrorRateTrigger {
+  type: 'lambda-error-rate';
+  properties: LambdaErrorRateTriggerProps;
+}
+
+interface LambdaErrorRateTriggerProps extends TriggerWithCustomComparison {
+  /**
+   * #### Fires when the percentage of failed Lambda invocations exceeds this value.
+   */
+  thresholdPercent: number;
+}
+
+interface LambdaDurationTrigger {
+  type: 'lambda-duration';
+  properties: LambdaDurationTriggerProps;
+}
+
+interface LambdaDurationTriggerProps extends TriggerWithCustomComparison, TriggerWithCustomStatFunction {
+  /**
+   * #### Fires when Lambda execution time exceeds this value (ms).
+   *
+   * ---
+   *
+   * Default: fires if **average** duration > threshold. Customize with `statistic` and `comparisonOperator`.
+   */
+  thresholdMilliseconds: number;
+}
+
+interface RelationalDatabaseFreeMemoryTrigger {
+  type: 'database-free-memory';
+  properties: RelationalDatabaseFreeMemoryTriggerProps;
+}
+
+interface RelationalDatabaseFreeMemoryTriggerProps extends TriggerWithCustomComparison, TriggerWithCustomStatFunction {
+  /**
+   * #### Fires when free memory drops below this value (MB).
+   *
+   * ---
+   *
+   * Default: fires if **average** free memory < threshold. Customize with `statistic` and `comparisonOperator`.
+   */
+  thresholdMB: number;
+}
+
+interface RelationalDatabaseReadLatencyTrigger {
+  type: 'database-read-latency';
+  properties: RelationalDatabaseReadLatencyTriggerProps;
+}
+
+interface RelationalDatabaseReadLatencyTriggerProps extends TriggerWithCustomComparison, TriggerWithCustomStatFunction {
+  /**
+   * #### Fires when average read I/O latency exceeds this value (seconds).
+   */
+  thresholdSeconds: number;
+}
+
+interface RelationalDatabaseWriteLatencyTrigger {
+  type: 'database-write-latency';
+  properties: RelationalDatabaseWriteLatencyTriggerProps;
+}
+
+interface RelationalDatabaseWriteLatencyTriggerProps
+  extends TriggerWithCustomComparison,
+    TriggerWithCustomStatFunction {
+  /**
+   * #### Fires when average write I/O latency exceeds this value (seconds).
+   */
+  thresholdSeconds: number;
+}
+
+interface RelationalDatabaseCPUUtilizationTrigger {
+  type: 'database-cpu-utilization';
+  properties: RelationalDatabaseCPUUtilizationTriggerProps;
+}
+
+interface RelationalDatabaseCPUUtilizationTriggerProps
+  extends TriggerWithCustomComparison,
+    TriggerWithCustomStatFunction {
+  /**
+   * #### Fires when CPU utilization exceeds this percentage.
+   */
+  thresholdPercent: number;
+}
+
+interface RelationalDatabaseFreeStorageTrigger {
+  type: 'database-free-storage';
+  properties: RelationalDatabaseFreeStorageTriggerProps;
+}
+
+interface RelationalDatabaseFreeStorageTriggerProps extends TriggerWithCustomComparison, TriggerWithCustomStatFunction {
+  /**
+   * #### Fires when free disk space drops below this value (MB).
+   *
+   * ---
+   *
+   * Default: fires if **minimum** free storage < threshold.
+   */
+  thresholdMB: number;
+}
+
+interface RelationalDatabaseConnectionCountTrigger {
+  type: 'database-connection-count';
+  properties: RelationalDatabaseConnectionCountTriggerProps;
+}
+
+interface RelationalDatabaseConnectionCountTriggerProps
+  extends TriggerWithCustomComparison,
+    TriggerWithCustomStatFunction {
+  /**
+   * #### Fires when the number of active database connections exceeds this value.
+   */
+  thresholdCount: number;
+}
+
+interface TriggerWithCustomStatFunction {
+  /**
+   * #### How to aggregate metric values within each period: `avg`, `sum`, `min`, `max`, `p90`, `p95`, `p99`.
+   *
+   * @default avg
+   */
+  statistic?: StatisticFunction;
+}
+interface TriggerWithCustomComparison {
+  /**
+   * #### How to compare the metric value against the threshold.
+   *
+   * @default GreaterThanThreshold
+   */
+  comparisonOperator?: ComparisonOperator;
+}
+
+type StatisticFunction = 'avg' | 'p90' | 'p95' | 'p99' | 'min' | 'max' | 'sum';
+
+type ComparisonOperator =
+  | 'GreaterThanThreshold'
+  | 'GreaterThanOrEqualToThreshold'
+  | 'LessThanThreshold'
+  | 'LessThanOrEqualToThreshold';
+
+type AlarmNotificationEventRuleInput = {
+  description: string;
+  time: string;
+  alarmAwsResourceName: string;
+  stackName: string;
+  alarmConfig: AlarmDefinition;
+  affectedResource: AlarmAffectedResourceInfo;
+  comparisonOperator: ComparisonOperator;
+  measuringUnit: string;
+  alarmLink: string;
+  statFunction: string;
+};
+
+type AlarmAffectedResourceInfo = {
+  displayName: string;
+  link: string;
+  logLink?: string;
+};
+```

package/ai-docs/config-ref/sqs-queue.md

@@ -0,0 +1,232 @@
+---
+docType: config-ref
+title: Sqs Queue
+resourceType: sqs-queue
+tags:
+  - sqs-queue
+  - sqs
+  - queue
+  - message-queue
+source: types/stacktape-config/sqs-queues.d.ts
+priority: 1
+---
+
+# Sqs Queue
+
+Message queue for decoupling services. Producers send messages, consumers process them at their own pace.
+
+Fully managed, serverless, pay-per-message. Use for background processing, task queues, or buffering between services.
+
+Resource type: `sqs-queue`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Message queue for decoupling services. Producers send messages, consumers process them at their own pace.
+ *
+ * ---
+ *
+ * Fully managed, serverless, pay-per-message. Use for background processing, task queues, or buffering between services.
+ */
+interface SqsQueue {
+  type: 'sqs-queue';
+  properties?: SqsQueueProps;
+  overrides?: ResourceOverrides;
+}
+
+interface SqsQueueProps {
+  /**
+   * #### Delay (in seconds) before new messages become visible to consumers. Range: 0–900.
+   *
+   * ---
+   *
+   * Useful for introducing a buffer, e.g., waiting for related data to be available before processing.
+   *
+   * @default 0
+   */
+  delayMessagesSecond?: number;
+  /**
+   * #### Maximum message size in bytes. Range: 1,024 (1 KB) to 262,144 (256 KB).
+   *
+   * ---
+   *
+   * Messages larger than this limit are rejected. For payloads over 256 KB, store the data in S3 and send the reference.
+   *
+   * @default 262144
+   */
+  maxMessageSizeBytes?: number;
+  /**
+   * #### How long unprocessed messages stay in the queue before being deleted. Range: 60s to 1,209,600s (14 days).
+   *
+   * ---
+   *
+   * Default is 4 days (345,600s). Increase if consumers might fall behind or be temporarily offline.
+   *
+   * @default 345600
+   */
+  messageRetentionPeriodSeconds?: number;
+  /**
+   * #### Seconds the queue waits for messages before returning an empty response. Range: 0–20.
+   *
+   * ---
+   *
+   * Set to `1`–`20` to enable long polling, which reduces costs by making fewer API calls.
+   * With short polling (`0`), the consumer gets an immediate (often empty) response and must poll again.
+   *
+   * Recommended: `20` for most workloads — it's the most cost-effective.
+   *
+   * @default 0
+   */
+  longPollingSeconds?: number;
+  /**
+   * #### How long (seconds) a message is hidden from other consumers after being received. Range: 0–43,200 (12 hours).
+   *
+   * ---
+   *
+   * After a consumer picks up a message, it must delete it before this timeout expires — otherwise it becomes
+   * visible again and can be processed by another consumer (duplicate processing).
+   *
+   * Set this higher than your expected processing time. If your tasks take 2 minutes, use at least 150 seconds.
+   *
+   * @default 30
+   */
+  visibilityTimeoutSeconds?: number;
+  /**
+   * #### Creates a FIFO queue that guarantees message order and exactly-once delivery.
+   *
+   * ---
+   *
+   * Use when processing order matters (e.g., financial transactions, sequential workflows).
+   * FIFO queues have lower throughput (~300 msg/s without batching, ~3,000 with) compared to standard queues.
+   *
+   * Requires either `contentBasedDeduplication: true` or a `MessageDeduplicationId` on each message.
+   *
+   * @default false
+   */
+  fifoEnabled?: boolean;
+  /**
+   * #### Enables high-throughput mode for FIFO queues (up to ~70,000 msg/s per queue).
+   *
+   * ---
+   *
+   * Messages are partitioned by `MessageGroupId` — order is guaranteed within each group but not across groups.
+   * Requires `fifoEnabled: true`.
+   */
+  fifoHighThroughput?: boolean;
+  /**
+   * #### Automatically deduplicates messages based on their content (SHA-256 hash of the body).
+   *
+   * ---
+   *
+   * Within the 5-minute deduplication window, identical messages are delivered only once.
+   * Saves you from having to generate a unique `MessageDeduplicationId` for each message.
+   * Requires `fifoEnabled: true`.
+   */
+  contentBasedDeduplication?: boolean;
+  /**
+   * #### Moves messages that fail processing too many times to a dead-letter queue for inspection.
+   *
+   * ---
+   *
+   * After `maxReceiveCount` failed attempts, the message is automatically moved to a separate queue
+   * so you can investigate and reprocess it. Prevents poison messages from blocking the queue.
+   */
+  redrivePolicy?: SqsQueueRedrivePolicy;
+  /**
+   * #### Additional alarms associated with this resource.
+   *
+   * ---
+   *
+   * These alarms will be merged with any alarms configured globally in the [console](https://console.stacktape.com/alarms).
+   */
+  alarms?: SqsQueueAlarm[];
+  /**
+   * #### Disables globally configured alarms for this resource.
+   *
+   * ---
+   *
+   * Provide a list of alarm names as configured in the [console](https://console.stacktape.com/alarms).
+   */
+  disabledGlobalAlarms?: string[];
+  /**
+   * #### Custom access-control statements added to the queue's resource policy.
+   *
+   * ---
+   *
+   * These are merged with policies Stacktape auto-generates. Use to grant cross-account access or allow
+   * specific AWS services (e.g., SNS) to send messages to this queue.
+   */
+  policyStatements?: SqsQueuePolicyStatement[];
+  /**
+   * #### A list of event sources that trigger message delivery to this queue.
+   *
+   * ---
+   *
+   * Currently supports EventBridge event bus integration for delivering events directly to the queue.
+   */
+  events?: SqsQueueEventBusIntegration[];
+}
+
+interface SqsQueuePolicyStatement {
+  /**
+   * #### `Allow` or `Deny` access for the specified actions and principal.
+   */
+  Effect: string;
+  /**
+   * #### SQS actions to allow or deny. E.g., `["sqs:SendMessage"]` or `["sqs:*"]`.
+   */
+  Action: string[];
+  /**
+   * #### Optional conditions for when this statement applies (e.g., restrict by source ARN or IP range).
+   */
+  Condition?: any;
+  /**
+   * #### Who gets access: AWS account ID, IAM ARN, or `"*"` for everyone. E.g., `{ "Service": "sns.amazonaws.com" }`.
+   */
+  Principal: any;
+}
+
+/**
+ * #### Routes events from an EventBridge event bus to this queue when they match a specified pattern.
+ */
+interface SqsQueueEventBusIntegration {
+  type: 'event-bus';
+  /**
+   * #### Properties of the integration
+   */
+  properties: SqsQueueEventBusIntegrationProps;
+}
+
+interface SqsQueueEventBusIntegrationProps extends EventBusIntegrationProps {
+  /**
+   * #### Message group ID for FIFO queues. Required when the target queue has `fifoEnabled: true`.
+   *
+   * ---
+   *
+   * Messages in the same group are processed in strict order. Different groups can be processed in parallel.
+   */
+  messageGroupId?: string;
+}
+
+interface SqsQueueRedrivePolicy {
+  /**
+   * #### Name of another `sqs-queue` in your config to use as the dead-letter queue.
+   */
+  targetSqsQueueName?: string;
+  /**
+   * #### ARN of an external SQS queue to use as the dead-letter queue. Use when the DLQ is in another stack or account.
+   */
+  targetSqsQueueArn?: string;
+  /**
+   * #### How many times a message can be received (and fail) before being moved to the dead-letter queue.
+   *
+   * ---
+   *
+   * A typical starting value is `3`–`5`. Set lower for fast-failing workloads, higher for retryable transient errors.
+   */
+  maxReceiveCount: number;
+}
+
+type SqsQueueReferencableParam = 'arn' | 'name' | 'url';
+```