AWS AppSync Event API Instructions

# AWS AppSync Event API Instructions

Use these instructions when implementing AWS AppSync **Event API** handlers (`onPublish`, `onSubscribe`) with the `APPSYNC_JS` runtime.

## Scope And Contract

- Design handlers around channel namespace flow: `onPublish` runs before broadcast, `onSubscribe` runs on subscription attempts.
- Keep event contracts explicit and stable. Treat channel path and payload shape as API contracts.
- Prefer additive changes for payload fields and avoid breaking existing subscribers.

## Data Sources Map (Event API)

Use data sources intentionally based on event workflow needs:

- Lambda: custom compute, transformation, orchestration, external AWS/service integrations.
- DynamoDB: low-latency event/state persistence and key-based reads/writes.
- RDS (Aurora): relational checks, joins, and stronger relational integrity use cases.
- EventBridge: route events into broader event-driven architectures.
- OpenSearch: search and analytics over event data.
- HTTP endpoints: external APIs or AWS service APIs over HTTP.
- Bedrock: model inference and AI enrichment in event pipelines.

Prefer combining multiple data sources only when each hop has a clear reason (auth, persistence, enrichment, routing).

## Data Source Setup And IAM (Required)

- Create data sources at the Event API level, then attach them as namespace integrations.
- If using a service role, grant only required actions (least privilege).
- Trust policy principal must allow `appsync.amazonaws.com` to assume the role.
- Restrict trust with conditions when possible:
  - `aws:SourceAccount` to your account.
  - `aws:SourceArn` to a specific AppSync API ARN (or tightly scoped pattern).
- Do not reuse broad, cross-service IAM roles for AppSync data source access.

## Runtime Restrictions (Must Follow)

The `APPSYNC_JS` runtime is a constrained JavaScript subset. Write code for this environment, not for full Node.js.

- Do not use async patterns: no promises, `async/await`, or background async workflows.
- Do not use unsupported statements/operators: `try/catch/finally`, `throw`, `while`, C-style `for(;;)`, `continue`, labels, unsupported unary operators.
- Do not rely on network or file system access from runtime code. Use AppSync data sources for I/O.
- Do not use recursion or pass functions as function arguments.
- Do not rely on classes or advanced runtime features outside documented support.
- Prefer `for-of` / `for-in` loops when iteration is needed.

## Handler Flow Patterns

- For handlers without data source integration, return transformed `ctx.events` directly.
- For handlers with data sources, use object form with `request(ctx)` and `response(ctx)`.
- Use `runtime.earlyReturn(...)` when business logic decides to skip data source invocation and response mapping.
- Use `ctx.info.channel.path`, `ctx.info.channel.segments`, `ctx.info.channelNamespace.name`, and `ctx.info.operation` to drive routing logic.
- For `onPublish` with data source integration, return the event list to broadcast from `response(ctx)`.
- For `onSubscribe` with data source integration, include a `response(ctx)` function (it can be empty when no follow-up mapping is needed).

### `ctx.prev.result` vs `ctx.stash` (Pipeline Guidance)

- If resolver/functions execute step-by-step and the next step depends on the previous step output, use `ctx.prev.result`.
- Use `ctx.prev.result` as the default data handoff mechanism between consecutive pipeline functions.
- Use `ctx.stash` when you need shared data across multiple pipeline stages that is not just the immediate previous result.
- Store only small, intentional metadata in `ctx.stash` (for example flags, IDs, correlation context), not large payload copies.
- Do not duplicate full previous results into `ctx.stash` when `ctx.prev.result` already provides the needed value.

## Error And Authorization Flow

- Do not use `throw` in handlers. Use `util.error(...)` and `util.appendError(...)` patterns supported by AppSync runtime.
- For publish failures, return explicit runtime errors with safe messages (no internals).
- For business-level authorization rejection at handler level, use the documented unauthorized utility in handler code.
- Keep error payloads non-sensitive. Never expose secrets, raw stack traces, or internal identifiers.

## Built-In Utilities

Use `util` for runtime-safe helpers.

- Encoding utilities:
  - `util.urlEncode`, `util.urlDecode`
  - `util.base64Encode`, `util.base64Decode`
- Runtime utility:
  - `runtime.earlyReturn(obj)` to stop current handler execution and skip data source + response evaluation.

## Built-In Modules

Use official modules from `@aws-appsync/utils` and keep code declarative.

- DynamoDB module import:
  - `import * as ddb from '@aws-appsync/utils/dynamodb'`
- RDS module import:
  - `import { ... } from '@aws-appsync/utils/rds'`

### DynamoDB Usage

Prefer module helpers over handwritten request objects where possible.

- Core helpers include: `get`, `put`, `remove`, `update`, `query`, `scan`, `sync`.
- Batch helpers: `batchGet`, `batchPut`, `batchDelete`.
- Transaction helpers: `transactGet`, `transactWrite`.
- For `update`, prefer operation helpers like increment/append/add/remove for safe patch-style mutations.
- Model keys and indexes for query-first access. Avoid `scan` unless justified.
- Use conditions for correctness and optimistic concurrency when needed.
- For bursty publish flows, prefer `batchPut`/`batchDelete` (or `transactWrite` when atomicity is required) over many single-item operations.
- Keep DynamoDB batch sizes within service/API limits and chunk inputs deterministically.

### Lambda Usage

For Event API Lambda data source requests, use:

- `operation: 'Invoke'`
- optional `invocationType: 'RequestResponse' | 'Event'`
- `payload` shaped explicitly for the Lambda contract

Guidance:

- Use `RequestResponse` when handler flow depends on Lambda output.
- Use `Event` only for fire-and-forget side effects.
- Validate `ctx.result` in `response(ctx)` and map to the exact outgoing event shape.
- In Event API handlers, Lambda operation support is `Invoke`; do not rely on GraphQL-style `BatchInvoke` here.
- If you need batching with Lambda in Event API flows, send an array payload in one `Invoke` and implement item-level aggregation/partial-failure handling inside Lambda.

### Direct Lambda Integration (No Handler Code)

You can configure namespace handlers with direct Lambda integrations (`Behavior: DIRECT`) instead of writing `onPublish`/`onSubscribe` code.

- `REQUEST_RESPONSE` mode:
  - `onPublish` Lambda returns `{ events?: OutgoingEvent[], error?: string }`.
  - `onSubscribe` Lambda returns `null` for success or `{ error: string }` for rejection.
- `EVENT` mode:
  - Invocation is asynchronous; AppSync does not wait for a Lambda response.
  - For publish, events continue broadcasting as usual.
- If Lambda returns `error` in request/response mode, it is logged when logging is enabled, and not sent back as a detailed internal error payload.

Prefer direct Lambda integration when the entire namespace behavior can be centralized in Lambda and you do not need APPSYNC_JS request/response mapping logic.

### HTTP/EventBridge/RDS/OpenSearch/Bedrock

When using non-DynamoDB data sources:

- HTTP: return `resourcePath`, `method`, optional `params` (`headers`, `query`, `body`); check `ctx.result.statusCode`, `ctx.result.body`, and `ctx.error`.
- EventBridge: use `operation: 'PutEvents'` and build deterministic event entries from `ctx.events`.
- RDS: prefer SQL helpers and `createPgStatement`/`createMySQLStatement`; do not interpolate unsafe SQL.
- OpenSearch: keep request path/params explicit and map only required fields from `ctx.result`.
- Bedrock: define `operation` (`InvokeModel` or `Converse`) explicitly and include prompt-injection safeguards.

## Batch Operations (Required Guidance)

- Prefer batching where the target data source natively supports it and event semantics allow grouping.
- DynamoDB:
  - Use `batchGet`, `batchPut`, `batchDelete` for non-atomic bulk operations.
  - Use `transactGet`, `transactWrite` when atomic all-or-nothing behavior is required.
  - Validate and cap per-request item counts; chunk large batches.
- Lambda:
  - Event API JS handler requests use `operation: 'Invoke'` with optional `invocationType`.
  - There is no Event API `BatchInvoke` operation in handler request objects.
  - For pseudo-batch Lambda patterns, send list payloads to one invoke and return deterministic per-item result structures.
- Keep ordering guarantees explicit: if downstream consumers depend on order, preserve and document ordering keys.

## Security And Data Safety

- Treat `ctx.identity`, headers, and payload fields as untrusted input.
- Enforce least-privilege IAM per data source.
- Add validation before write operations and before forwarding transformed events.
- Never hardcode secrets in handler code.
- For public usage, keep defaults conservative (deny/unauthorized on invalid states).

## Tooling, TypeScript, And Build

- Use `@aws-appsync/eslint-plugin` (`plugin:@aws-appsync/base` at minimum).
- Use `plugin:@aws-appsync/recommended` when TypeScript tooling is configured.
- TypeScript is not executed directly by AppSync runtime. Transpile to supported JavaScript before deployment.
- Bundle with externalized `@aws-appsync/utils` imports and source maps for debugging.

## Observability And Operations

- Enable CloudWatch logging for handlers and datasource integration.
- Log with structured, low-cardinality fields (channel namespace/path, operation, request id).
- Add alarmable signals: handler errors, datasource errors, latency regression.
- Keep response transformations deterministic and test with multi-event payloads.

## Minimum Quality Checklist

- [ ] Uses only APPSYNC_JS-supported runtime features.
- [ ] No `throw`, no async/promise usage, no unsupported loop/control constructs.
- [ ] Error flow uses runtime-supported utilities and returns non-sensitive messages.
- [ ] `onPublish` and `onSubscribe` behavior is explicit and tested.
- [ ] Data source request/response mapping is deterministic and schema-safe.
- [ ] Lambda/DynamoDB contracts are documented and validated.
- [ ] Linting with `@aws-appsync/eslint-plugin` is enabled.