Working in aws-emulator

Developer and agent guide for this EmulatorCore-generated emulator project for aws services. (The repository's README.md is the project's own, user-facing document; this file is the working guide for anyone — human or agent — editing the emulator.)

Specification

• Type: Smithy
• SDK: aws
• Emulator Core: v0.1.0
• Layout: per-service crate (multi-service)

Project Structure

This project uses the per-crate layout: every service is its own Cargo crate, so changing one service recompiles only that crate instead of the whole emulator.

aws-emulator/
├── Cargo.toml           # workspace: one member per service, plus router
├── services/service-<name>/  # ONE CRATE PER SERVICE — this is where you work
│   ├── Cargo.toml
│   ├── build.rs         # calls emulator_core_build_support::generate(...)
│   ├── smithy-model/    # <name>.json — the Smithy model (drives the wire protocol)
│   └── src/
│       ├── lib.rs       # #[smithy_service] decl (generated by build.rs)
│       ├── service.rs   # impl Service — can_handle + routing/refusal overrides (yours to edit)
│       ├── state.rs     # this service's in-memory state struct
│       ├── scaffolded.rs # the 501 channel, and `validation` to refuse a bad request
│       └── ops/         # ONE FILE PER OPERATION — add handlers here
├── core/router/         # binary: assembles every service into one emulator
│   ├── src/lib.rs       # build_router: register_connector + ops::register_all per
│   │                    #   service. RE-RENDERED on every service add — do not edit
│   └── src/main.rs      # the boot path; emitted once — do not edit
├── vendor/              # vendored, agent-immutable framework (path deps)
│   ├── engine/          # the SINGLE shared InMemoryEngine (do not fork)
│   └── build-support/   # shared build.rs codegen
└── issues/              # issue tracking

Which files do I edit?

When .emulator/license-header exists, every new .rs file starts with its contents, copied exactly, followed by a blank line.

An operation that executes user code or serves a native data-plane protocol follows the contract in the module docs of vendor/engine/src/lib.rs.

Leave every @auth/@optionalAuth trait in smithy-model/ as shipped, and never override auth_schemes() to return an empty list: an operation is unsigned only when the model makes it so.

There are two kinds of credentials:

• The emulator's own (root) credentials, ctx.callback().credentials() and ctx.callback().aws_credentials_provider(), only sign this operation's in-process calls to other services. Never put them in a response or a log: anyone holding them can sign any request. They are not in the credential store.
• Created credentials are what an operation returns to its caller (an access key, a session). Create them with ctx.credential_store().create(&AWS_ACCESS_KEY) or &AWS_SESSION, return the id and secrets you get back, write none to a file or log, and delete them with delete(id); never construct an id or a secret yourself.

A URL an operation returns for the caller to fetch later must lead back to this emulator:

• A presigned URL (a download or upload location, a callback URL): sign it with ctx.url_signer().sign(SignedUrlRequest::new(method, signing_name, path), expires_in), with path decoded as the model lays it out, and return url.as_str(). Return expires_at() and required_headers() as well when the output has members for them. Code without a context (state, a background task) is handed a clone of ctx.url_signer(). Never write X-Amz-Signature yourself or presign with an AWS SDK: that URL reaches the real service or fails verification.
• An unsigned address (a queue URL, a resource endpoint): ctx.endpoint() followed by the resource's path. Never build it from <service>.<region>.amazonaws.com.

The emulator verifies every request signature: a service never checks signatures itself.

Quick Start

Build

cargo build                        # whole workspace
cargo build -p service-<name>      # ONE service (this is the fast path)

Run the emulator

cargo run -p aws-emulator-router

The router binds the emulator API and its GET /__admin/health readiness endpoint on :9297 (self-signed HTTPS). Override with EMULATOR_DATA_PORT or -p.

Test one service in-process (no socket)

fn build_service() -> service_<name>::EmulatedService<engine::InMemoryEngine> {
    let engine = std::sync::Arc::new(engine::InMemoryEngine::new());
    service_<name>::EmulatedService::new(engine)
}

EmulatedService::new(engine) constructs each operation from the single shared engine (the engine-as-constructor seam); there is no builder and no per-operation registration step. Each operation reaches the shared store through self.engine.