Skip to content

Conversation

@agents-git-bot
Copy link
Contributor

Summary

This PR syncs documentation changes from cloudflare/sandbox-sdk PR #306: Simplify port token storage and improve documentation.

Changes

Enhanced architecture documentation (concepts/architecture.mdx):

  • Added three-layer architecture breakdown with detailed responsibilities
  • Documented client architecture pattern with modular client design
  • Added container runtime architecture details

New concurrency model documentation (concepts/concurrency.mdx):

  • Comprehensive guide to concurrency across all layers (Workers, Durable Objects, Container, Shell)
  • Explains Cloudflare-specific patterns (input/output gates, blockConcurrencyWhile)
  • Provides best practices for building reliable concurrent applications
  • Helps developers understand when operations are serialized vs parallel

Updated session management (concepts/sessions.mdx):

  • Added command execution model section explaining foreground vs background execution
  • Documented command serialization behavior
  • Explained how stdout/stderr separation works

Why these changes matter

The original PR added comprehensive architecture and concurrency documentation to the SDK repository to help contributors and AI assistants understand the system. These same concepts are valuable for SDK users who need to:

  • Understand how requests flow through the system
  • Build reliable applications that handle concurrency correctly
  • Avoid race conditions when using Durable Object storage
  • Understand when commands run sequentially vs in parallel

Related

Syncs documentation from cloudflare/sandbox-sdk PR #306:
- Enhanced architecture.mdx with three-layer breakdown, client patterns, and container runtime details
- Added concurrency.mdx explaining the concurrency model across all layers (Workers, Durable Objects, Container, Shell)
- Updated sessions.mdx with command execution model details

These additions help developers understand the system architecture and build reliable concurrent applications.

Related to: cloudflare/sandbox-sdk#306
@github-actions
Copy link
Contributor

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/src/content/docs/sandbox/ @whoiskatrin, @ghostwriternr, @cloudflare/pcx-technical-writing, @cloudflare/ai-agents

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants