Smithy TypeScript

Smithy TypeScript provides two approaches for building Server SDKs (SSDKs). While the Traditional SSDK relies heavily on code generation (creating specific classes for each input and handler), the New Schema-based SSDK uses the Smithy schema to drive behavior.

Key Architectural Differences

• Protocol Support: The Schema SSDK supports multi-protocol environments. Using createCombinedRouter, a single server can handle RPC v2, AWS JSON RPC, and HTTP binding routers simultaneously via automatic protocol claiming.
• Handler Signature: In the Schema SSDK, handlers receive metadata through a dedicated context argument rather than requiring interceptor wiring. The signature is: handler(input, serverCtx, userCtx).
• Error Handling: The Schema SSDK uses a unified onError hook which replaces the traditional ValidationCustomizer. This hook handles validation errors, authentication failures, and handler exceptions in one place.
• Metadata Access: The ServerRequestContext provides typed access to headers, path, query, operation name, and caller identity.
• Validation: The Schema SSDK uses validateServerSchema to traverse the schema (checking length, range, pattern, uniqueItems, and required fields) rather than relying solely on static .validate() methods on generated classes.

Known Limitations

• Per-operation configuration: The Schema SSDK uses a single service-level handler. This means all operations share one authentication and interceptor chain, unlike the Traditional SSDK where each operation can have independent configuration.
• Event Streams: Neither the Traditional nor the Schema-based SSDK currently supports event streams.

The schema-based server supports Amazon Event Stream wire format for three streaming patterns. In TypeScript, streaming members appear as AsyncIterable<T>.

Streaming Patterns

Implementation Guide

• Output-only: Return an async generator for the response stream.
• Input-only: Use for await to consume the incoming stream.
• Bidirectional: Use for await to consume the input and return an async generator for the output.

Note on Lambda: AWS Lambda does not support incoming request streams or bidirectional streams. Output-only streams are supported via Lambda response streaming (awslambda.streamifyResponse) with HTTP API (v2). For full support, use @smithy/server-node on EC2/ECS/Fargate.

const serviceHandler = new MyServiceHandler({
  protocols: [/* ... */],
  handlers: {
    // Output-only
    async SubscribeToEvents(input) {
      return {
        subscriptionId: "sub-123",
        events: (async function* () {
          yield { notification: { topic: "news", payload: "update" } };
        })(),
      };
    },

    // Input-only
    async PublishEvents(input) {
      let count = 0;
      for await (const event of input.events) {
        count++;
      }
      return { eventCount: count, message: "Done" };
    },

    // Bidirectional
    async Chat(input) {
      const inputMessages = input.messages;
      return {
        sessionId: "session-1",
        messages: (async function* () {
          for await (const msg of inputMessages) {
            yield { response: { text: `Got: ${msg.message?.text}` } };
          }
        })(),
      };
    },
  },
});

When generating a client, the artifacts are organized into a specific structure. If you are generating custom files (like paginators or waiters), it is recommended to use a separate directory for separation of concerns.

A typical generated structure includes:

• src/commands/: Individual command classes.
• src/models/: Types and interfaces exported from the Smithy model.
• src/runtimeConfig*.ts: Platform-specific runtime configurations (Shared, Node.js, Browser, React-Native).
• src/index.ts: The main entry point.
• package.json and tsconfig*.json: Configuration files for the generated package.

build/smithy/source/typescript-client-codegen/
├── package.json
├── src
│   ├── Weather.ts
│   ├── WeatherClient.ts
│   ├── commands/
│   ├── extensionConfiguration.ts
│   ├── index.ts
│   ├── models/
│   ├── pagination/
│   ├── runtimeConfig.browser.ts
│   ├── runtimeConfig.native.ts
│   ├── runtimeConfig.shared.ts
│   ├── runtimeConfig.ts
│   └── runtimeExtensions.ts
├── tsconfig.cjs.json
├── tsconfig.es.json
├── tsconfig.json
└── tsconfig.types.json

The generated server SDK provides a subclass of SchemaServiceHandler. You implement the business logic by providing async functions for every operation defined in your Smithy model. The handler abstracts away HTTP request/response transformations and provides typed inputs and outputs.

When implementing the handler, you provide a handlers object where each key corresponds to an operation. Each handler function receives:

• input: The typed input shape for the operation.
• context: A ServerRequestContext object.
• userContext: A generic context object provided during instantiation.

// Generated code example
export class GreetingServiceHandler<Context = {}> extends SchemaServiceHandler<Context> {
  constructor(
    options: SchemaServiceHandlerOptions<Context> & {
      handlers: {
        SayHello: (
          input: SayHelloInput,
          context: ServerRequestContext,
          userContext: Context
        ) => Promise<SayHelloOutput>;
        GetItem: (input: GetItemInput, context: ServerRequestContext, userContext: Context) => Promise<GetItemOutput>;
      };
    }
  ) {
    super({
      ...options,
      validationEnabled: options.validationEnabled ?? true,
      operationSchemas: options.operationSchemas ?? OPERATION_SCHEMAS,
    });
  }

  public async handle(request: HttpRequest, context: Context): Promise<HttpResponse>;
}