feat(container): close Cloudflare Container feature gaps

[prisis]

Summary

Brings @lunora/container up to feature parity with Cloudflare Containers, implementing the missing capabilities subclass-first on the LunoraContainer base — no @cloudflare/containers fork or vendoring. Shims are written to be deleted when the corresponding upstream PRs ship.

Across the branch:

• Multi-port routing — requiredPorts + .port(n) on .get()/.any()/.pool() handles.
• Egress firewall — allowedHosts/deniedHosts/interceptHttps config plus runtime handle.egress.* controls (allow/deny/set*/remove*), routed through the re-exported ContainerProxy entrypoint.
• Activity-timeout controls — renewActivityTimeout() to keep a busy-WebSocket container awake (WebSocket connections don't renew activity timeout - container sleeps despite active connections cloudflare/containers#147).
• Observability — labels config, typed instance state, and structured start/stop/error/sleep lifecycle events surfaced in lunora dev + Studio Logs.
• hardTimeout — a total-lifetime cap armed via the base scheduler, run-generation-stamped so a stale timer from a slept/crashed run can't kill a fresh one; default onHardTimeoutExpired → stop() (feat: Add hard timeout functionality to Container class cloudflare/containers#85).
• readyOn — declarative application-readiness probes that gate request proxying until each path returns its expected status, probed directly over getTcpPort to avoid recursing the start path (feat: user-defined readiness checks via readyOn cloudflare/containers#188).
• Outbound handlers — surface Cloudflare's custom outbound-handler types from @lunora/container/do (Feature: Support Outbound Workers-like request interception cloudflare/containers#135).

Notes

• defineContainer config stays pure data (codegen/config read it Node-side), so readyOn is modelled as descriptors, not handler functions.
• image() (CC-7953: add image() to Container cloudflare/containers#227) was intentionally not shipped: ContainerInfo in current workers-types has no image field, so it would return undefined — genuinely runtime-blocked.
• Fixed a barrel gap: ContainerReadinessCheck is now re-exported from the package root.

Docs

• New Multi-port and Egress firewall sections in docs/index.mdx, plus Readiness gating, Hard timeout, and a build-time args note.
• Config table completed to all 20 ContainerConfig fields; buildArgs documented in both the README and the docs page.

Testing

@lunora/container: 89 tests pass · tsc --noEmit clean · eslint clean · prettier clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added support for multi-port container routing and readiness probes.
  • Added egress controls, including allow/deny host lists and HTTPS interception options.
  • Added hard timeouts and runtime timeout renewal for container instances.
  • Exposed additional container metadata and lifecycle states.

• Bug Fixes

  • Improved timeout handling so older scheduled stops won’t affect newer container runs.
  • Preserved requested port routing across retries.

• Documentation

  • Expanded container docs and examples with the latest configuration and runtime options.

[netlify]

✅ Deploy Preview for lunorash ready!

Name	Link
🔨 Latest commit	6ec7a3a
🔍 Latest deploy log	https://app.netlify.com/projects/lunorash/deploys/6a4128cc64e0b50008695229
😎 Deploy Preview	https://deploy-preview-36--lunorash.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Warning

Review limit reached

@prisis, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 30 minutes and 22 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ec01997c-7038-4601-badf-e98de2e2a323

📥 Commits

Reviewing files that changed from the base of the PR and between 490aa35 and 6ec7a3a.

⛔ Files ignored due to path filters (1)

• packages/container/__tests__/define-container.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**

📒 Files selected for processing (2)

• packages/container/docs/index.mdx
• packages/container/src/define-container.ts

Walkthrough

Adds multi-port routing (.port(n)), egress firewall controls (allowedHosts, deniedHosts, interceptHttps, runtime egress.*), application readiness probes (readyOn), hard-timeout lifecycle (hardTimeout, onHardTimeoutExpired), and build-time buildArgs/labels/entrypoint to @lunora/container. Includes type definitions, validation, DO implementation, client handle surface, codegen template changes, and documentation updates.

Changes

Container feature expansion

Layer / File(s)	Summary
Type contracts packages/container/src/types.ts, packages/container/src/lifecycle-event.ts, packages/container/src/client.ts, packages/container/src/index.ts	Adds ContainerReadinessCheck, extends ContainerConfig with egress/readiness/lifecycle fields, introduces ContainerEgressControls, widens ContainerInstanceHandle and ContainerInstanceState, adds "sleep" to ContainerLifecycle, and re-exports new types from the package root.
defineContainer validation packages/container/src/define-container.ts	Adds parseDurationSeconds helper; introduces assertValidPort, assertValidReadyOnChecks, assertValidHardTimeout, and assertValidContainerRuntimeFields validators; wires them into defineContainer's validation flow.
DO implementation packages/container/src/do/index.ts	Updates LunoraContainer constructor to copy egress/port/label config fields; onStart arms hard timeout and awaits readiness probes; onHardTimeoutExpired validates a generation stamp to ignore stale schedules; adds armHardTimeout, awaitContainerReadiness, and awaitReadinessCheck; switches to named export and re-exports ContainerProxy and outbound types.
Client handle: port targeting, egress, pool, test double packages/container/src/client.ts	Introduces TARGET_PORT_HEADER, toRequest, and sendingHandle for port-aware fetch; wires egress controls and renewActivityTimeout onto instance handles; adds .port() to pooled handles; reworks createContainerTestContext via a new testNamespaceFor fake namespace.
Codegen template packages/codegen/src/emit.ts	Updates emitContainers template to use a named LunoraContainer import and adds ContainerProxy re-export from @lunora/container/do.
Documentation packages/container/README.md, packages/container/docs/index.mdx	Documents multi-port routing, egress firewall, readiness probes, hard timeout, buildArgs, labels, and an expanded defineContainer configuration table.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise, conventional-commit style, and accurately summarizes the main container feature-parity changes.
Description check	✅ Passed	The description covers the core template sections (Summary, Notes, Docs, Testing) and is detailed enough, though Linked issues/Checklist/CLA are omitted.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/container-coverage

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thank you for following the naming conventions! 🙏

[github-actions]

Thank you for confirming the Contributor License Agreement! 🙏

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

packages/codegen/src/emit.ts (1)

2043-2053: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Emit extensionless relative imports in the generated TS entrypoint.

The template still generates ../containers.js, and the emitted usage example still shows ./lunora/_generated/containers.js, so every generated .ts file keeps violating the repo's TS import convention.

Suggested fix

- * `export * from "./lunora/_generated/containers.js";`
+ * `export * from "./lunora/_generated/containers";`
@@
-import { ${imports} } from "../containers.js";
+import { ${imports} } from "../containers";

As per coding guidelines, **/*.{ts,tsx}: Write relative imports without file extensions.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/codegen/src/emit.ts` around lines 2043 - 2053, The generated
TypeScript entrypoint still uses an extensioned relative import, which violates
the repo’s TS import convention. Update the template in emit.ts so the generated
entrypoint imports from the relative containers module without “.js”, and make
sure any emitted usage example for the containers entrypoint also omits the file
extension. Check the entrypoint template around the LunoraContainer and
ContainerProxy export section, plus any helper that renders the usage snippet,
so all generated .ts output is extensionless.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/container/docs/index.mdx`:
- Around line 386-388: The docs for the container options are describing env as
if it were build-time, which conflicts with the runtime behavior defined in the
types and the surrounding docs. Update the option description in the table for
env to match the runtime start-time semantics used by the container
configuration, and keep buildArgs as the only build-time setting; use the same
terminology as packages/container/src/types.ts and the adjacent section to avoid
confusing env with buildArgs.
- Around line 213-215: The health check docs for the container platform
misdescribe pingEndpoint as an alternative open port; update the text around the
health check/readiness explanation in the docs index so it clearly says
defaultPort is the port checked, while pingEndpoint is the HTTP path Cloudflare
polls on that container. Keep the wording aligned with the contract defined in
pingEndpoint in packages/container/src/types.ts and the surrounding
readyOn/ctx.containers.<name> description.

In `@packages/container/src/define-container.ts`:
- Around line 243-287: The runtime config validator in
assertValidContainerRuntimeFields currently misses interceptHttps, so invalid
values can slip through from plain JS callers and be copied by do/index.ts onto
the container instance. Add a type/shape check for config.interceptHttps in
define-container.ts alongside the other field validations, rejecting anything
that is not a boolean or omitted, and keep the error message consistent with the
existing defineContainer: validation style.
- Around line 208-222: `assertValidReadyOnChecks` currently accepts readiness
paths with leading or trailing whitespace because it only checks
`trim().length`, while `do/index.ts` later uses the raw `readyOn[].path` value.
Update the validation in `define-container.ts` so `readyOn[].path` must already
be trimmed (reject any value whose trimmed form differs from the original),
alongside the existing non-empty string check. Keep the fix localized to
`assertValidReadyOnChecks` and use the existing
`defineContainer`/`readyOn[].path` validation path to fail fast before readiness
probing starts.

---

Nitpick comments:
In `@packages/codegen/src/emit.ts`:
- Around line 2043-2053: The generated TypeScript entrypoint still uses an
extensioned relative import, which violates the repo’s TS import convention.
Update the template in emit.ts so the generated entrypoint imports from the
relative containers module without “.js”, and make sure any emitted usage
example for the containers entrypoint also omits the file extension. Check the
entrypoint template around the LunoraContainer and ContainerProxy export
section, plus any helper that renders the usage snippet, so all generated .ts
output is extensionless.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b4ebc2e2-9ff4-4e46-8bec-04865bbc19df

📥 Commits

Reviewing files that changed from the base of the PR and between 0d1c96c and 490aa35.

⛔ Files ignored due to path filters (4)

• packages/codegen/__tests__/discover-containers.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
• packages/container/__tests__/client.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
• packages/container/__tests__/define-container.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
• packages/container/__tests__/lunora-container.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**

📒 Files selected for processing (9)

• packages/codegen/src/emit.ts
• packages/container/README.md
• packages/container/docs/index.mdx
• packages/container/src/client.ts
• packages/container/src/define-container.ts
• packages/container/src/do/index.ts
• packages/container/src/index.ts
• packages/container/src/lifecycle-event.ts
• packages/container/src/types.ts

[codspeed-hq]

Merging this PR will not alter performance

✅ 4 untouched benchmarks
⏩ 145 skipped benchmarks¹

---

_{Comparing feat/container-coverage (6ec7a3a) with alpha (2fa5023)²}

Footnotes

1. 145 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on alpha (0d1c96c) during the generation of this report, so 2fa5023 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩