# Smithy Smithy TypeScript Server SDK `@smithy/server-common` ## Alpha software The Smithy TypeScript Server SDK is an alpha release, and breaking changes may happen between minor versions in the `0.x` range. ## Intro This library provides the runtime components for Smithy schema-based server SDKs in TypeScript. It contains the `SchemaServiceHandler` request pipeline, protocol implementations (Smithy RPC v2 CBOR, AWS REST JSON, AWS JSON RPC), routing, input validation, interceptors, auth scheme support, and metrics integration. The remainder of this document walks through the end-to-end process of going from a Smithy model to a running schema-based server behind Amazon API Gateway. ## Authoring a Smithy Model A Smithy model defines your service's API contract of operations, input/output shapes, errors, and protocol traits. Both the server and client SDKs are generated from this model. See https://smithy.io/ for details. Create a model file (e.g. `models/main.smithy`): ```smithy $version: "2.0" namespace com.example.greeting use smithy.protocols#rpcv2Cbor /// A simple greeting service. @rpcv2Cbor service GreetingService { version: "2024-01-01" operations: [SayHello, GetItem] errors: [ServiceError] } operation SayHello { input := { @required @length(min: 1, max: 100) name: String } output := { @required greeting: String } } @readonly operation GetItem { input := { @required itemId: String } output := { @required itemId: String @required name: String description: String } errors: [ItemNotFound] } @error("client") structure ItemNotFound { @required message: String } @error("server") structure ServiceError { message: String } ``` ## Generating a Schema-Based Server SDK The `typescript-server-codegen` plugin always generates a schema-based server SDK. The generated package uses static operation schemas for routing, serde, and validation. Add the following to your `smithy-build.json`: ```json { "version": "1.0", "sources": ["models"], "maven": { "dependencies": ["software.amazon.smithy.typescript:smithy-typescript-codegen:0.52.0"] }, "projections": { "server": { "plugins": { "typescript-server-codegen": { "service": "com.example.greeting#GreetingService", "package": "@example/greeting-service-server", "packageVersion": "0.0.1" } } } } } ``` Run code generation: ```shell smithy build ``` The generated server SDK will be in `build/smithy/server/typescript-server-codegen/`. It includes: - **`src/server/GreetingServiceHandler.ts`** — A generated factory and typed options requiring handler implementations for every operation. Operation schemas and modeled protocol defaults are pre-wired. - **`src/schemas/schemas_0.ts`** — Static operation schema tuples (`StaticOperationSchema[]`) describing each operation's HTTP binding, input/output structure shapes, and constraint metadata. - **`src/models/`** — TypeScript interfaces for every input, output, and error shape. - **`src/index.ts`** — Barrel export of the handler, schemas, models, and errors. The generated handler factory allows you to provide async functions that work directly on typed input and output shapes, abstracting away HTTP request and response transformations. You supply one handler function per modeled operation: ```typescript // Simplified generated API export type GreetingServiceHandlerOptions = { handlers: { SayHello: ServerOperation; GetItem: ServerOperation; }; // Interceptors, auth schemes, metrics, and optional protocol overrides. }; export function createGreetingServiceHandler(options: GreetingServiceHandlerOptions): SchemaServiceHandler { // Generated operation schemas and modeled protocol defaults are supplied here. return new SchemaServiceHandler(/* ... */); } ``` Build the generated server package: ```shell cd build/smithy/server/typescript-server-codegen yarn && yarn build ``` ## Generating a Client SDK From the same Smithy model, you can also generate a client SDK using the `typescript-client-codegen` plugin within `smithy-build.json`: ```json { "version": "1.0", "sources": ["models"], "maven": { "dependencies": ["software.amazon.smithy.typescript:smithy-typescript-codegen:0.52.0"] }, "projections": { "server": { "plugins": { "typescript-server-codegen": { "service": "com.example.greeting#GreetingService", "package": "@example/greeting-service-server", "packageVersion": "0.0.1" } } }, "client": { "plugins": { "typescript-client-codegen": { "service": "com.example.greeting#GreetingService", "package": "@example/greeting-service-client", "packageVersion": "0.0.1" } } } } } ``` After `smithy build`, the client SDK is in `build/smithy/client/typescript-client-codegen/`. It provides: - **Client class** (`GreetingServiceClient`) with endpoint and protocol configuration. - **Command classes** (`SayHelloCommand`, `GetItemCommand`) for each operation. - **Types** for all inputs, outputs, and errors. Build the generated client package: ```shell cd build/smithy/client/typescript-client-codegen yarn && yarn build ``` ### Client usage ```typescript import { GreetingServiceClient, SayHelloCommand, GetItemCommand } from "@example/greeting-service-client"; const client = new GreetingServiceClient({ endpoint: "https://your-api-id.execute-api.us-east-1.amazonaws.com/prod", }); const response = await client.send(new SayHelloCommand({ name: "World" })); console.log(response.greeting); // "Hello, World!" ``` ## Using the Generated Server with the API Gateway Adapter The `@smithy/server-apigateway` package adapts the schema-based service handler to run as an AWS Lambda function behind API Gateway. It converts API Gateway proxy events (v1 and v2) into framework-owned `ServerRequest` objects and converts `HttpResponse` objects back into the proxy result format that API Gateway expects. ### Installation In your Lambda function's package, add dependencies on the generated server SDK and the adapter: ```json { "dependencies": { "@example/greeting-service-server": "0.0.1", "@smithy/server-apigateway": "^0.2.0", "@smithy/server-common": "^0.2.0" } } ``` ### Writing the Lambda Handler The integration involves three steps: 1. Instantiate the generated service handler with your operation implementations. 2. Convert the incoming API Gateway event to a `ServerRequest` using `createServerRequest`. 3. Handle the request and convert the response back to API Gateway format. ```typescript import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2, Context } from "aws-lambda"; // generated handler import { createGreetingServiceHandler } from "@example/greeting-service-server"; // converters for APIG import { createServerRequest, convertVersion2Response } from "@smithy/server-apigateway"; // Create the handler once outside the Lambda entry point so it is reused // across warm invocations. const serviceHandler = createGreetingServiceHandler({ handlers: { async SayHello(input) { return { greeting: `Hello, ${input.name}!`, }; }, async GetItem(input, requestContext) { // Your business logic — call DynamoDB, etc. const item = await fetchItemFromDatabase(input.itemId); if (!item) { // Throw a modeled error; the framework serializes it properly as a 400 or 500 // depending on the modeled error fault attribution. const error = new Error(`Item ${input.itemId} not found`); error.name = "ItemNotFound"; (error as any).$fault = "client"; throw error; } return { itemId: item.itemId, name: item.name, description: item.description, }; }, }, }); // Lambda entry point export async function handler(event: APIGatewayProxyEventV2, context: Context): Promise { const serverRequest = createServerRequest(event, context); const httpResponse = await serviceHandler.handle(serverRequest); return convertVersion2Response(httpResponse); } ``` ### Multi-Protocol Support The schema-based server can serve multiple protocols simultaneously from the same handler. The framework inspects request headers to route to the correct protocol: ```typescript import { SmithyRpcV2CborServerProtocol, AwsRestJsonServerProtocol, AwsJsonRpcServerProtocol, } from "@smithy/server-common"; const serviceHandler = createGreetingServiceHandler({ // you can provide 1 or more ServerProtocols. This is optional! // If you don't provide a "protocols" array, the handler will // automatically identify and support all known wire protocols. protocols: [ new SmithyRpcV2CborServerProtocol({ defaultNamespace: "com.example.greeting" }), new AwsRestJsonServerProtocol({ defaultNamespace: "com.example.greeting" }), new AwsJsonRpcServerProtocol({ defaultNamespace: "com.example.greeting" }), ], handlers: {/* ... */}, }); ``` Clients using any of the registered protocols will be handled correctly. ```ts import { AwsJson1_0Protocol, AwsJson1_1Protocol, AwsRestJsonProtocol, AwsSmithyRpcV2CborProtocol, } from "@aws-sdk/config/protocol"; import { GreetingServiceClient, SayHelloCommand, GetItemCommand } from "@example/greeting-service-client"; const client = new GreetingServiceClient({ endpoint: "https://your-api-id.execute-api.us-east-1.amazonaws.com/prod", protocol: AwsJson1_0Protocol, }); const client2 = new GreetingServiceClient({ endpoint: "https://your-api-id.execute-api.us-east-1.amazonaws.com/prod", protocol: AwsSmithyRpcV2CborProtocol, }); // Both clients can communicate with the same server using different protocols. ``` ### API Gateway v1 (REST API) For API Gateway REST APIs using the v1 payload format, use `convertVersion1Response`: ```typescript import type { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from "aws-lambda"; import { createServerRequest, convertVersion1Response } from "@smithy/server-apigateway"; export async function handler(event: APIGatewayProxyEvent, context: Context): Promise { const serverRequest = createServerRequest(event, context); const httpResponse = await serviceHandler.handle(serverRequest); return convertVersion1Response(httpResponse); } ``` ### Event Streams The schema-based server supports the [Amazon Event Stream](https://smithy.io/2.0/aws/amazon-eventstream.html) wire format for streaming operations. Event streams enable long-lived bidirectional communication between client and server using typed events. There are three streaming patterns: | Pattern | Client sends | Server sends | | ------------------------------- | -------------------- | --------------------- | | **Output-only** (server→client) | Normal request | Event stream response | | **Input-only** (client→server) | Event stream request | Normal response | | **Bidirectional** | Event stream request | Event stream response | #### Smithy model ```smithy /// Output-only: server streams notifications to the client. operation SubscribeToEvents { input := { @httpHeader("x-channel") channel: String } output := { @httpHeader("x-subscription-id") subscriptionId: String @httpPayload events: NotificationStream } } /// Input-only: client streams events to the server. operation PublishEvents { input := { @httpHeader("x-channel") channel: String @httpPayload events: PublishStream } output := { eventCount: Integer message: String } } /// Bidirectional: both sides stream simultaneously. operation Chat { input := { @httpHeader("x-session-id") sessionId: String @httpPayload messages: ChatStream } output := { @httpHeader("x-session-id") sessionId: String @httpPayload messages: ChatStream } } @streaming union NotificationStream { notification: Notification heartbeat: Heartbeat } @streaming union PublishStream { /* ... */ } @streaming union ChatStream { /* ... */ } ``` #### Server handler implementation Event stream members appear as `AsyncIterable` in both input and output types. To consume an incoming stream, iterate it with `for await`. To produce an outgoing stream, return an async generator. ```typescript const serviceHandler = createMyServiceHandler({ protocols: [/* ... */], handlers: { // Output-only: return an async generator for the response stream. async SubscribeToEvents(input) { const channel = input.channel ?? "default"; return { subscriptionId: `sub-${channel}`, events: (async function* () { for (let i = 0; i < 10; i++) { yield { notification: { topic: channel, payload: `event-${i}` } }; await sleep(1000); } })(), }; }, // Input-only: consume the incoming stream, return a normal response. async PublishEvents(input) { let count = 0; for await (const event of input.events) { count++; processEvent(event); } return { eventCount: count, message: `Processed ${count} events` }; }, // Bidirectional: consume input stream and produce output stream. async Chat(input) { const inputMessages = input.messages; return { sessionId: `ack-${input.sessionId}`, messages: (async function* () { for await (const msg of inputMessages) { // Echo back a response for each incoming message. yield { response: { text: `Got: ${msg.message?.text}` } }; } })(), }; }, }, }); ``` #### Client-side usage From the client SDK, event stream operations use the same async iterable pattern: ```typescript import { MyServiceClient, SubscribeToEventsCommand, PublishEventsCommand } from "@example/my-client"; const client = new MyServiceClient({ endpoint: "http://localhost:8080" }); // Output-only: iterate the response stream. const response = await client.send(new SubscribeToEventsCommand({ channel: "news" })); console.log(response.subscriptionId); for await (const event of response.events) { console.log(event.notification?.payload); } // Input-only: pass an async generator as the request stream. await client.send( new PublishEventsCommand({ channel: "metrics", events: (async function* () { yield { metric: { name: "cpu", value: 0.85 } }; yield { metric: { name: "mem", value: 0.6 } }; })(), }) ); ``` #### HTTP transport requirements Event streams use the `application/vnd.amazon.eventstream` binary framing format. - **Output-only streams** work over HTTP/1.1 using chunked transfer encoding on the response. - **Input-only streams** can work over HTTP/1.1 (chunked request body) or HTTP/2, depending on the service's `eventStreamHttp` trait. - **Bidirectional streams** require HTTP/2 for full-duplex communication. See the [`@smithy/server-node` README](../server-node/README.md) for an example of setting up an HTTP/2 server that supports bidirectional event streams. When the service's protocol trait includes `eventStreamHttp: ["h2"]`, the generated client automatically uses `NodeHttp2Handler`: ```smithy @rpcv2Cbor( http: ["h2", "http/1.1"] eventStreamHttp: ["h2"] ) service MyService { /* ... */ } ``` Output-only event streams work over HTTP/1.1 (the request is normal; only the response body streams). #### RPC vs REST protocol differences For **RPC protocols** (Smithy RPC v2 CBOR, AWS JSON 1.0/1.1), non-stream members of the input/output are serialized as an `initial-request` or `initial-response` message — the first event in the stream. For **REST protocols** (AWS restJson1), non-stream members are bound to HTTP headers, URI path labels, or query parameters. They do not appear in the event stream itself. The event stream member must carry `@httpPayload`. #### Lambda / API Gateway limitations > **Important:** AWS Lambda does not support incoming request streams or > bidirectional event streams. The Lambda execution model buffers the full > request body before invoking the handler, and does not support streaming > the request. > > - **Output-only streams** (server→client) are supported via Lambda response > streaming (`awslambda.streamifyResponse`) with HTTP API (API Gateway v2). > - **Input-only and bidirectional streams** are **not supported** on Lambda. > These require a long-lived connection (e.g., a Node.js HTTP/2 server on > EC2, ECS, or Fargate). > > The `@smithy/server-apigateway` adapter does not support event stream > operations. Use `@smithy/server-node` with an HTTP/2 server for full > event stream support. ### Passing Request-Scoped Attributes Each `ServerRequest` contains a mutable `userAttributes` map for request-scoped application data. Operation handlers can read the map from their framework-provided context: ```typescript export async function handler(event: APIGatewayProxyEventV2, context: Context): Promise { const serverRequest = createServerRequest(event, context); serverRequest.userAttributes.set("lambdaRequestId", context.awsRequestId); serverRequest.userAttributes.set("accountId", event.requestContext.accountId); const httpResponse = await serviceHandler.handle(serverRequest); return convertVersion2Response(httpResponse); } ``` Operation handlers receive the framework context as their second argument: ```typescript handlers: { async SayHello(input, requestContext) { const lambdaRequestId = requestContext.userAttributes.get("lambdaRequestId"); const accountId = requestContext.userAttributes.get("accountId"); console.log(`Request ${lambdaRequestId} from ${accountId}`); console.log(`Operation: ${requestContext.operation}`); return { greeting: `Hello, ${input.name}!` }; }, } ``` The `requestContext` (second argument) is always provided by the framework and contains: - `request` — the original framework request state - `operation` — the resolved operation name - `operationDefinition` — the generated schema for the operation - `identity` — the request identity, including an authenticated caller when present - `userAttributes` — request-scoped application data - `metricsRecorder` — the request metrics recorder, when configured ### Input Validation The schema-based server validates deserialized input against Smithy constraint traits before invoking your handler. This is enabled by default (`validationEnabled: true`). Supported constraints include: - `@required` — member must be present - `@length` — string/list/map length bounds - `@range` — numeric min/max bounds - `@pattern` — regex pattern matching - `@uniqueItems` — list elements must be distinct - `@enum` / `@intEnum` — restricted value sets When validation fails, the framework returns a `ValidationException` error response to the client without calling your handler. To disable validation: ```typescript const serviceHandler = createGreetingServiceHandler({ protocols: [/* ... */], handlers: {/* ... */}, validationEnabled: false, }); ``` ### Adding Auth Schemes Configure auth schemes when creating the service handler. Schemes are tried in array order; the first to return a non-null `Caller` wins. If all schemes return null, the framework responds with `UnauthenticatedException`: ```typescript const serviceHandler = createGreetingServiceHandler({ handlers: {/* ... */}, authSchemes: [ { name: "api-key", async authenticate(request) { const key = request.headers["x-api-key"]; if (!key) return null; // decline — try next scheme const principal = await validateApiKey(key); return { principal }; }, }, ], }); ``` The authenticated `Caller` is available via `requestContext.identity.caller` in your handlers. ### Adding Interceptors Interceptors hook into the request pipeline for cross-cutting concerns. There are two kinds of hooks: - **Read hooks** (`read*`) — observe a pipeline step without modifying it. - **Modify hooks** (`modify*`) — return a replacement value for the next step. ```typescript const serviceHandler = createGreetingServiceHandler({ handlers: {/* ... */}, interceptors: [ { readBeforeExecution({ request }) { console.log(`→ ${request.method} ${request.path}`); }, modifyBeforeValidation({ input, operation }) { // Normalize input before validation runs if (operation === "SayHello" && typeof (input as any).name === "string") { return { ...(input as any), name: (input as any).name.trim() }; } return input; }, modifyBeforeSerialization({ output, operation }) { // Add a computed field to every response return { ...(output as any), servedAt: new Date().toISOString() }; }, readAfterExecution({ operation, error }) { if (error) console.error(`✗ ${operation}:`, error); }, }, ], }); ``` The full interceptor hook order is: 1. `readBeforeExecution` 2. `readAfterAuthentication` 3. `modifyBeforeDeserialization` → can replace the `HttpRequest` 4. `readAfterDeserialization` 5. `modifyBeforeValidation` → can replace the deserialized input 6. `readBeforeInvocation` 7. _(handler invocation)_ 8. `readAfterInvocation` 9. `modifyBeforeSerialization` → can replace the handler output 10. `readAfterSerialization` 11. `modifyBeforeCompletion` → can replace the `HttpResponse` 12. `readAfterExecution` ### Metrics Configure a `MetricsRecorderFactory` when creating the service handler. The framework creates one recorder per request and records lifecycle timings: ```typescript const serviceHandler = createGreetingServiceHandler({ handlers: {/* ... */}, metricsRecorderFactory: { create() { return createMetricsRecorder(); }, }, }); ``` ### Error Handling The `onError` callback lets you intercept errors before they are serialized: ```typescript const serviceHandler = createGreetingServiceHandler({ protocols: [/* ... */], handlers: {/* ... */}, onError(operation, error) { // Log all errors console.error(`[${operation}]`, error); // Return undefined to use default error handling return undefined; }, }); ``` ### API Gateway Configuration Configure your API Gateway with a catch-all proxy route so all requests are forwarded to the Lambda function and routed by the Smithy server internally: - **HTTP API (v2):** Use a `$default` route or `ANY /{proxy+}` integration pointing to the Lambda. - **REST API (v1):** Use a `{proxy+}` resource with `ANY` method and Lambda proxy integration enabled. The schema-based handler performs its own routing using protocol headers and operation schemas, so API Gateway only needs to forward the raw HTTP request. ### Request Pipeline When a request arrives, `createServerRequest()` transforms the API Gateway event into framework-owned request state, and the `SchemaServiceHandler` executes the following steps in order: 1. **Route** — Inspect request headers and path to determine which registered protocol claims the request, then resolve the target operation name. 2. **Authenticate** — Run registered auth schemes in order. The first to return a `Caller` wins; if all decline, respond with `UnauthenticatedException`. 3. **Deserialize** — Parse the request body into a typed input object using the matched protocol's serde logic. 4. **Validate** — Check the deserialized input against Smithy constraint traits (`@required`, `@length`, `@range`, `@pattern`, etc.). Reject with `ValidationException` on failure. 5. **Invoke** — Call your operation handler with the validated input. 6. **Serialize** — Encode the handler's output into an `HttpResponse` using the matched protocol. The resulting `HttpResponse` is then passed to `convertVersion2Response()` (or `convertVersion1Response()`) to produce the final API Gateway result. Interceptor hooks run between each step, providing observe-only and mutation extension points at every boundary. If any step throws, the error path serializes an appropriate error response using the matched protocol.