Aws-Appsync

# 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 pub