# Container Echo (/docs/experiments/container-echo)



Echo a message through **Cloudflare Containers**. A Durable Object subclass (`EchoContainer`) extends `@cloudflare/containers`'s `Container` and proxies requests to a Node HTTP server running in the container image.

## API Reference [#api-reference]

### POST /echo [#post-echo]

Send `text/plain` or JSON (`{ "message": "..." }` or `{ "echo": "..." }`).

Body must be non-empty and at most 10,000 characters.

#### Example Request [#example-request]

```bash
curl -X POST "https://your-worker.workers.dev/echo" \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'
```

#### Success Response [#success-response]

```json
{
  "echo": "hello",
  "port": 8080
}
```

#### Error Codes [#error-codes]

* `400` - Invalid or empty body (`INVALID_BODY`)
* `502` - Container or proxy failure (`ECHO_ERROR`)

## Use Cases [#use-cases]

* Learn Containers + Durable Object lifecycle with a minimal API
* Prototype Worker-to-container request forwarding
* Validate Dockerfile-backed images on Cloudflare
* Compare Containers vs pure Workers for Node-style servers

## Limitations [#limitations]

* Docker must be available for `wrangler dev` / deploy image builds
* Message body capped at 10,000 characters
* Demo exposes a single echo path; not a general proxy
* Container instances are limited (`max_instances: 2` in wrangler)

## Deployment [#deployment]

<Steps>
  <Step>
    ### Click the deploy button [#click-the-deploy-button]

    [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/shrinathsnayak/cloudflare-experiments/tree/main/apps/experiments/container-echo)
  </Step>

  <Step>
    ### Deploy [#deploy]

    Wrangler builds `./Dockerfile`, registers the `EchoContainer` Durable Object, and binds it as `ECHO`.
  </Step>

  <Step>
    ### Test your deployment [#test-your-deployment]

    ```bash
    curl -X POST "https://your-worker.workers.dev/echo" \
      -H "Content-Type: text/plain" \
      -d "hello"
    ```
  </Step>
</Steps>

## Local Development [#local-development]

Docker must be running for container image builds.

```bash
cd apps/experiments/container-echo
npm install
npm run dev
```

```bash
curl -X POST "http://localhost:8787/echo" \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'
```

Unit tests mock the Durable Object binding so Docker is not required for `npm run test`.

## Configuration [#configuration]

`wrangler.json` declares:

* **Container** `EchoContainer` from `./Dockerfile` (port 8080)
* **Durable Object binding** `ECHO` → `EchoContainer`
* **Migration** `v1` with `new_sqlite_classes: ["EchoContainer"]`

## Cloudflare Features Used [#cloudflare-features-used]

* **[Workers](https://developers.cloudflare.com/workers/)** - Edge compute runtime
* **[Containers](https://developers.cloudflare.com/containers/)** - Dockerfile-backed runtime on Cloudflare
* **[Durable Objects](https://developers.cloudflare.com/durable-objects/)** - Container lifecycle via `@cloudflare/containers`