{"0": {
    "doc": "Architecture",
    "title": "Architecture",
    "content": "Internal design and implementation details. ",
    "url": "/architecture.html",
    
    "relUrl": "/architecture.html"
  },"1": {
    "doc": "Architecture",
    "title": "Table of contents",
    "content": ". | Overview | Module Structure | Key Design Decisions | Data Flow . | Session Creation | Message Flow (Outgoing) | Message Flow (Incoming) | Retransmission Flow | . | Concurrency Model . | Session Tasks | . | Error Handling . | Error Types | Error Propagation | . | Security Architecture | Performance Characteristics | Extension Points | Python Bindings Architecture . | Python API | Context Manager Support | . | . ",
    "url": "/architecture.html#table-of-contents",
    
    "relUrl": "/architecture.html#table-of-contents"
  },"2": {
    "doc": "Architecture",
    "title": "Overview",
    "content": "aws-ssm-bridge is a flat-module Rust library implementing the AWS SSM Session Manager protocol. ┌─────────────────────────────────────────────────────────────┐ │ Python Bindings (PyO3 + pyo3-asyncio) │ ├─────────────────────────────────────────────────────────────┤ │ Public API: SessionManager, Session, SessionBuilder │ ├─────────────────────────────────────────────────────────────┤ │ Connection: WebSocket, Routing, Retransmit, Metrics │ ├─────────────────────────────────────────────────────────────┤ │ Protocol: Binary (116B header), JSON, Handshake, ACK │ ├─────────────────────────────────────────────────────────────┤ │ AWS SDK: SSM Client, Credentials, StartSession API │ └─────────────────────────────────────────────────────────────┘ . ",
    "url": "/architecture.html#overview",
    
    "relUrl": "/architecture.html#overview"
  },"3": {
    "doc": "Architecture",
    "title": "Module Structure",
    "content": "src/ ├── lib.rs # Public API re-exports ├── binary_protocol.rs # 116-byte binary header, SHA-256 digest ├── protocol.rs # Message types, JSON payloads, SessionType ├── session.rs # Session lifecycle, state machine ├── connection.rs # WebSocket, message routing, retransmit scheduler ├── ack.rs # ACK tracking, RTT (Jacobson/Karels), buffers ├── handshake.rs # 3-phase handshake protocol ├── builder.rs # Fluent SessionBuilder API ├── port_forward.rs # TCP tunneling ├── documents.rs # Type-safe SSM document definitions ├── rate_limit.rs # Token bucket rate limiting ├── metrics.rs # Pluggable observability hooks ├── shutdown.rs # Graceful shutdown coordination ├── pool.rs # Session pool for concurrent sessions ├── reconnect.rs # Auto-reconnection with exponential backoff ├── tracing_ext.rs # Structured tracing with spans ├── interactive.rs # Terminal raw mode, shell ├── terminal.rs # Cross-platform terminal handling ├── channels.rs # Broadcast multiplexer (fan-out) ├── retry.rs # Exponential backoff, circuit breaker ├── errors.rs # Error types ├── aws_client.rs # AWS SDK wrapper └── python/ # PyO3 bindings ├── mod.rs # Module exports └── session.rs # Python wrappers . ",
    "url": "/architecture.html#module-structure",
    
    "relUrl": "/architecture.html#module-structure"
  },"4": {
    "doc": "Architecture",
    "title": "Key Design Decisions",
    "content": "| Decision | Rationale | . | Flat modules | Industry standard (tokio, serde), simpler imports | . | Broadcast channels | Multiple output consumers, proper fan-out | . | tokio-tungstenite | AWS SDK uses Tokio, mature WebSocket impl | . | bytes::Bytes | Zero-copy, reference-counted buffers | . | aws-lc-rs | AWS’s libcrypto, hardware-accelerated SHA-256 | . | tokio::sync::Notify | Efficient shutdown signaling | . | forbid(unsafe_code) | Memory safety guarantee | . ",
    "url": "/architecture.html#key-design-decisions",
    
    "relUrl": "/architecture.html#key-design-decisions"
  },"5": {
    "doc": "Architecture",
    "title": "Data Flow",
    "content": "Session Creation . Application │ ▼ SessionManager::new().await │ (loads AWS credentials) ▼ SessionConfig │ ▼ AWS SSM StartSession API │ (returns: session_id, stream_url, token) ▼ Session::new() │ ├─▶ ConnectionManager::connect() │ │ │ ├─▶ WebSocket to wss://ssmmessages.{region}.amazonaws.com │ │ │ ├─▶ Handshake (open_data_channel → request → response → complete) │ │ │ └─▶ Spawn: message_loop, retransmit_scheduler │ └─▶ Return Session handle . Message Flow (Outgoing) . session.send(data) │ ▼ ManagerCommand::SendData │ (via mpsc channel) ▼ ConnectionManager │ ├─▶ Create StreamingMessage (seq, payload) │ ├─▶ OutgoingMessageBuffer::add() │ (track for retransmit) │ ├─▶ Serialize: binary header (116B) + payload │ ├─▶ Metrics: counter(messages_sent), counter(bytes_sent) │ └─▶ WebSocket::send(Binary) . Message Flow (Incoming) . WebSocket::recv() │ ▼ StreamingMessage::deserialize() │ ├─▶ Metrics: counter(messages_received), counter(bytes_received) │ ▼ Sequence Number Check │ ├─▶ seq &lt; expected: DUPLICATE → silently drop (no ACK) │ ├─▶ seq == expected: IN-ORDER → ACK, process, drain buffered │ │ │ └─▶ ChannelMultiplexer::broadcast(payload) │ │ │ └─▶ Application receives via session.output() │ └─▶ seq &gt; expected: OUT-OF-ORDER → buffer, ACK (non-sequential) . Retransmission Flow . tokio::interval(200ms) │ ▼ OutgoingMessageBuffer::get_retransmit_candidates() │ ├─▶ For each unacked message past RTO: │ │ │ ├─▶ Retransmit counter++ │ │ │ ├─▶ If counter &gt; 3000 (5 min): signal termination │ │ │ ├─▶ Else: WebSocket::send(Binary) │ │ │ └─▶ Metrics: counter(retransmissions) │ └─▶ (continues) . ",
    "url": "/architecture.html#data-flow",
    
    "relUrl": "/architecture.html#data-flow"
  },"6": {
    "doc": "Architecture",
    "title": "Concurrency Model",
    "content": ". | Fully async: Built on Tokio runtime | Message passing: mpsc channels (unbounded for commands, bounded for data) | Shared state: Arc&lt;RwLock&lt;T&gt;&gt; / Arc&lt;Mutex&lt;T&gt;&gt; where necessary | Task-based: Each session spawns: . | Message processing loop | Retransmit scheduler | (Optional) Output stream consumers | . | . Session Tasks . Session │ ├─▶ ConnectionManager::run() │ │ │ ├─▶ WebSocket recv loop │ │ │ ├─▶ Command handler (send, terminate) │ │ │ └─▶ Retransmit scheduler (200ms interval) │ └─▶ ChannelMultiplexer │ └─▶ Broadcast channels for output . ",
    "url": "/architecture.html#concurrency-model",
    
    "relUrl": "/architecture.html#concurrency-model"
  },"7": {
    "doc": "Architecture",
    "title": "Error Handling",
    "content": "Error Types . pub enum Error { Aws(AwsError), WebSocket(WebSocketError), Protocol(ProtocolError), Session(SessionError), Transport(TransportError), Config(String), Timeout, Cancelled, InvalidState(String), Io(std::io::Error), } . Error Propagation . | Rust: Result&lt;T, Error&gt; consistently | Python: Converted to PyRuntimeError, PyValueError, etc. | Retryable vs Fatal: Handled by retry.rs circuit breaker | . ",
    "url": "/architecture.html#error-handling",
    
    "relUrl": "/architecture.html#error-handling"
  },"8": {
    "doc": "Architecture",
    "title": "Security Architecture",
    "content": "| Component | Protection | . | Credentials | Redacted Debug impl, skip in tracing | . | URLs | SSRF protection, AWS endpoint validation | . | Input | Bounds checking, max sizes enforced | . | Memory | forbid(unsafe_code) | . | Transport | TLS required (WSS only) | . ",
    "url": "/architecture.html#security-architecture",
    
    "relUrl": "/architecture.html#security-architecture"
  },"9": {
    "doc": "Architecture",
    "title": "Performance Characteristics",
    "content": "| Metric | Value | . | Serialization | 460+ MiB/s (16KB payloads) | . | Deserialization | 500+ MiB/s (16KB payloads) | . | Base64 | 3.97 GiB/s (SIMD-accelerated) | . | SHA-256 | 205-333 MiB/s (aws-lc-rs) | . | Memory per session | ~1-2 MB | . | CPU | Minimal, mostly IO-bound | . ",
    "url": "/architecture.html#performance-characteristics",
    
    "relUrl": "/architecture.html#performance-characteristics"
  },"10": {
    "doc": "Architecture",
    "title": "Extension Points",
    "content": ". | MetricsRecorder: Implement for Prometheus/OTel/StatsD | SessionPool: Custom pool policies | ReconnectConfig: Custom backoff strategies | . ",
    "url": "/architecture.html#extension-points",
    
    "relUrl": "/architecture.html#extension-points"
  },"11": {
    "doc": "Architecture",
    "title": "Python Bindings Architecture",
    "content": "Python asyncio │ ▼ pyo3-asyncio::future_into_py() │ ▼ Tokio runtime (shared) │ ▼ Rust async functions │ ▼ Result&lt;T, Error&gt; → PyResult&lt;T&gt; . Python API . | Class | Methods | . | SessionManager | new(), start_session(), terminate_session() | . | Session | send(), output(), terminate(), wait_for_ready(), is_ready() | . | SessionConfig | Constructor with all options | . | OutputStream | Async iterator (async for chunk in stream) | . Context Manager Support . async with await manager.start_session(\"i-xxx\") as session: await session.send(b\"ls\\n\") # Automatically terminated . ",
    "url": "/architecture.html#python-bindings-architecture",
    
    "relUrl": "/architecture.html#python-bindings-architecture"
  },"12": {
    "doc": "Binary Protocol",
    "title": "Binary Protocol",
    "content": "AWS SSM binary message format (116-byte header). ",
    "url": "/binary_protocol.html",
    
    "relUrl": "/binary_protocol.html"
  },"13": {
    "doc": "Binary Protocol",
    "title": "Table of contents",
    "content": ". | Message Format . | Field Specifications | . | Usage . | Creating Messages | Serialization | Deserialization | . | Payload Types . | Control Flags (PayloadType::Flag) | . | Message Flags | SHA-256 Digest | Performance | Reference | . ",
    "url": "/binary_protocol.html#table-of-contents",
    
    "relUrl": "/binary_protocol.html#table-of-contents"
  },"14": {
    "doc": "Binary Protocol",
    "title": "Message Format",
    "content": "Messages use a 120-byte total header (4-byte HL field + 116-byte fixed header): . | HL(4) | MessageType(32) | Ver(4) | CD(8) | Seq(8) | Flags(8) | MessageId(16) | PayloadDigest(32) | PayType(4) | PayLen(4) | Payload(variable) | . Field Specifications . | Field | Size | Type | Description | . | HeaderLength | 4 bytes | u32 | Always 116 (excludes HL field) | . | MessageType | 32 bytes | UTF-8 | Space-padded string | . | SchemaVersion | 4 bytes | u32 | Protocol version (1) | . | CreatedDate | 8 bytes | u64 | Unix timestamp (milliseconds) | . | SequenceNumber | 8 bytes | i64 | Message sequence number | . | Flags | 8 bytes | u64 | Bit flags (SYN=1, FIN=2) | . | MessageId | 16 bytes | UUID | Binary UUID (no hyphens) | . | PayloadDigest | 32 bytes | [u8; 32] | SHA-256 hash | . | PayloadType | 4 bytes | u32 | Enum 1-12 | . | PayloadLength | 4 bytes | u32 | Payload byte count | . | Payload | variable | bytes | Raw payload data | . Byte Order: Big-endian (network byte order) . ",
    "url": "/binary_protocol.html#message-format",
    
    "relUrl": "/binary_protocol.html#message-format"
  },"15": {
    "doc": "Binary Protocol",
    "title": "Usage",
    "content": "Creating Messages . use aws_ssm_bridge::binary_protocol::{ClientMessage, PayloadType}; use aws_ssm_bridge::protocol::MessageType; use bytes::Bytes; let payload = Bytes::from(\"ls -la\\n\"); let message = ClientMessage::new( MessageType::InputStreamData, 1, // sequence_number PayloadType::Output, payload, ); // SHA-256 digest is automatically computed // UUID and timestamp are automatically generated . Serialization . let binary_data = message.serialize()?; websocket.send(binary_data).await?; . Deserialization . use bytes::Bytes; let received = websocket.recv().await?; let message = ClientMessage::deserialize(Bytes::from(received))?; // Validation is automatic: // - Header length check // - Payload length vs actual payload // - SHA-256 digest verification . ",
    "url": "/binary_protocol.html#usage",
    
    "relUrl": "/binary_protocol.html#usage"
  },"16": {
    "doc": "Binary Protocol",
    "title": "Payload Types",
    "content": "All 12 AWS payload types are supported: . pub enum PayloadType { Output = 1, // stdout Error = 2, // stderr Size = 3, // terminal resize Parameter = 4, // session parameters HandshakeRequest = 5, // handshake from agent HandshakeResponse = 6, // handshake from client HandshakeComplete = 7, // handshake done EncChallengeRequest = 8, // encryption challenge EncChallengeResponse = 9,// encryption response Flag = 10, // control flags StdErr = 11, // explicit stderr ExitCode = 12, // process exit code } . Control Flags (PayloadType::Flag) . pub enum PayloadTypeFlag { DisconnectToPort = 1, // TCP connection closed TerminateSession = 2, // End session ConnectToPortError = 3, // Port unavailable } . ",
    "url": "/binary_protocol.html#payload-types",
    
    "relUrl": "/binary_protocol.html#payload-types"
  },"17": {
    "doc": "Binary Protocol",
    "title": "Message Flags",
    "content": "Bit flags for stream boundaries: . pub mod flags { pub const SYN: u64 = 1 &lt;&lt; 0; // First message pub const FIN: u64 = 1 &lt;&lt; 1; // Last message } message.flags = flags::SYN; // First message message.flags = flags::FIN; // Last message message.flags = flags::SYN | flags::FIN; // Single-message stream . ",
    "url": "/binary_protocol.html#message-flags",
    
    "relUrl": "/binary_protocol.html#message-flags"
  },"18": {
    "doc": "Binary Protocol",
    "title": "SHA-256 Digest",
    "content": "The payload digest is automatically computed during message creation and automatically validated during deserialization. // Automatic on creation let message = ClientMessage::new(...); // message.payload_digest = SHA256(payload) // Automatic on deserialization let parsed = ClientMessage::deserialize(data)?; // Returns error if digest doesn't match . ",
    "url": "/binary_protocol.html#sha-256-digest",
    
    "relUrl": "/binary_protocol.html#sha-256-digest"
  },"19": {
    "doc": "Binary Protocol",
    "title": "Performance",
    "content": "SHA-256 computation (using aws-lc-rs): . | Payload | Time | Throughput | . | 1 KB | ~5 µs | 200+ MiB/s | . | 16 KB | ~50 µs | 300+ MiB/s | . The library uses bytes::Bytes for zero-copy buffer management. ",
    "url": "/binary_protocol.html#performance",
    
    "relUrl": "/binary_protocol.html#performance"
  },"20": {
    "doc": "Binary Protocol",
    "title": "Reference",
    "content": ". | AWS Implementation: session-manager-plugin/messageparser.go | Module Source: src/binary_protocol.rs | . ",
    "url": "/binary_protocol.html#reference",
    
    "relUrl": "/binary_protocol.html#reference"
  },"21": {
    "doc": "Getting Started",
    "title": "Getting Started",
    "content": " ",
    "url": "/getting-started.html",
    
    "relUrl": "/getting-started.html"
  },"22": {
    "doc": "Getting Started",
    "title": "Table of contents",
    "content": ". | Prerequisites . | Required IAM Permissions | . | Installation . | Rust | Python | . | Usage . | Interactive Shell | Port Forwarding | Python Async | . | Configuration . | Timeouts | Feature Flags | . | Next Steps | . ",
    "url": "/getting-started.html#table-of-contents",
    
    "relUrl": "/getting-started.html#table-of-contents"
  },"23": {
    "doc": "Getting Started",
    "title": "Prerequisites",
    "content": ". | AWS Credentials with SSM permissions | Target with SSM agent installed (EC2, ECS, or on-premises) | Rust 1.81+ or Python 3.8+ | . Required IAM Permissions . { \"Version\": \"2012-10-17\", \"Statement\": [{ \"Effect\": \"Allow\", \"Action\": [\"ssm:StartSession\", \"ssm:TerminateSession\"], \"Resource\": \"*\" }] } . ",
    "url": "/getting-started.html#prerequisites",
    
    "relUrl": "/getting-started.html#prerequisites"
  },"24": {
    "doc": "Getting Started",
    "title": "Installation",
    "content": "Rust . [dependencies] aws-ssm-bridge = \"0.1\" tokio = { version = \"1\", features = [\"full\"] } . Python . pip install aws-ssm-bridge . ",
    "url": "/getting-started.html#installation",
    
    "relUrl": "/getting-started.html#installation"
  },"25": {
    "doc": "Getting Started",
    "title": "Usage",
    "content": "Interactive Shell . use aws_ssm_bridge::interactive::{InteractiveShell, InteractiveConfig}; #[tokio::main] async fn main() -&gt; anyhow::Result&lt;()&gt; { let config = InteractiveConfig::default(); let mut shell = InteractiveShell::new(config)?; // Connect and run interactive session // Handles raw mode, resize (SIGWINCH), signals (Ctrl+C/D/Z) shell.connect(\"i-0123456789abcdef0\").await?; shell.run().await?; Ok(()) } . Port Forwarding . use aws_ssm_bridge::{SessionManager, PortForwardConfig, PortForwarder}; #[tokio::main] async fn main() -&gt; anyhow::Result&lt;()&gt; { let manager = SessionManager::new().await?; let forwarder = PortForwarder::new(&amp;manager, PortForwardConfig { target: \"i-0123456789abcdef0\".into(), local_port: 8080, remote_port: 80, ..Default::default() }).await?; println!(\"Forwarding localhost:8080 -&gt; remote:80\"); forwarder.wait().await?; Ok(()) } . Python Async . import asyncio from aws_ssm_bridge import SessionManager async def main(): manager = await SessionManager.new() async with await manager.start_session(target=\"i-0123456789abcdef0\") as session: await session.send(b\"whoami\\n\") async for chunk in await session.output(): print(chunk.decode(), end=\"\") asyncio.run(main()) . ",
    "url": "/getting-started.html#usage",
    
    "relUrl": "/getting-started.html#usage"
  },"26": {
    "doc": "Getting Started",
    "title": "Configuration",
    "content": "Timeouts . use aws_ssm_bridge::SessionConfig; use std::time::Duration; let config = SessionConfig { target: \"i-xxx\".into(), connect_timeout: Duration::from_secs(30), idle_timeout: Duration::from_secs(20 * 60), max_duration: Some(Duration::from_secs(3600)), ..Default::default() }; . Feature Flags . [dependencies] aws-ssm-bridge = { version = \"0.1\", default-features = false, features = [\"interactive\"] } . | Feature | Description | Default | . | interactive | Terminal handling | ✅ | . | python | Python bindings | ❌ | . ",
    "url": "/getting-started.html#configuration",
    
    "relUrl": "/getting-started.html#configuration"
  },"27": {
    "doc": "Getting Started",
    "title": "Next Steps",
    "content": ". | Architecture - Design overview | Security - Threat model and mitigations | Binary Protocol - Wire format details | Protocol Flow - Sequence diagrams | . ",
    "url": "/getting-started.html#next-steps",
    
    "relUrl": "/getting-started.html#next-steps"
  },"28": {
    "doc": "Home",
    "title": "aws-ssm-bridge",
    "content": "A Rust implementation of the AWS Systems Manager (SSM) Session Manager protocol. Get Started GitHub . Disclaimer: This project is not affiliated with, endorsed by, or sponsored by Amazon Web Services, Inc. This is an independent implementation based on protocol analysis. ",
    "url": "/#aws-ssm-bridge",
    
    "relUrl": "/#aws-ssm-bridge"
  },"29": {
    "doc": "Home",
    "title": "Overview",
    "content": "aws-ssm-bridge provides a native Rust implementation of the AWS SSM Session Manager protocol, enabling programmatic access to EC2 instances, ECS containers, and on-premises servers without SSH or open inbound ports. Why This Library? . The official AWS Session Manager Plugin is a CLI binary written in Go. This library is designed for embedding in your applications: . | Interactive shells with proper terminal handling | Port forwarding via TCP tunneling | Session pooling for connection reuse | Async Python bindings via PyO3 | . ",
    "url": "/#overview",
    
    "relUrl": "/#overview"
  },"30": {
    "doc": "Home",
    "title": "Capabilities",
    "content": "| Feature | Description | . | Binary Protocol | Full 116-byte AWS header, SHA-256 digest validation | . | Reliable Delivery | Sequence tracking, ACK/retransmission, RTT estimation | . | Interactive Shell | Raw terminal mode, resize handling (SIGWINCH) | . | Port Forwarding | TCP tunneling via PortForwarder | . | Python | Async support, context managers, type stubs | . ",
    "url": "/#capabilities",
    
    "relUrl": "/#capabilities"
  },"31": {
    "doc": "Home",
    "title": "Quick Example",
    "content": "Rust . use aws_ssm_bridge::{SessionManager, SessionConfig}; use futures::StreamExt; #[tokio::main] async fn main() -&gt; anyhow::Result&lt;()&gt; { let manager = SessionManager::new().await?; let mut session = manager.start_session(SessionConfig { target: \"i-0123456789abcdef0\".into(), ..Default::default() }).await?; let mut output = session.output(); tokio::spawn(async move { while let Some(data) = output.next().await { print!(\"{}\", String::from_utf8_lossy(&amp;data)); } }); session.send(b\"hostname\\n\").await?; tokio::time::sleep(std::time::Duration::from_secs(2)).await; session.terminate().await?; Ok(()) } . Python . import asyncio from aws_ssm_bridge import AsyncSession async def main(): async with AsyncSession(\"i-0123456789abcdef0\") as session: await session.send(\"hostname\\n\") async for chunk in session.output(): print(chunk.decode(), end=\"\") asyncio.run(main()) . ",
    "url": "/#quick-example",
    
    "relUrl": "/#quick-example"
  },"32": {
    "doc": "Home",
    "title": "Security Properties",
    "content": "| Property | Implementation | . | Memory safety | #![forbid(unsafe_code)] | . | SSRF protection | AWS endpoint validation | . | Rate limiting | Token bucket (configurable) | . | TLS required | WSS only (no unencrypted WebSocket) | . Security Documentation → . ",
    "url": "/#security-properties",
    
    "relUrl": "/#security-properties"
  },"33": {
    "doc": "Home",
    "title": "License",
    "content": "MIT License. See LICENSE. ",
    "url": "/#license",
    
    "relUrl": "/#license"
  },"34": {
    "doc": "Home",
    "title": "Home",
    "content": " ",
    "url": "/",
    
    "relUrl": "/"
  },"35": {
    "doc": "Protocol Flow",
    "title": "Protocol Flow",
    "content": "Sequence diagrams for AWS SSM Session Manager. ",
    "url": "/protocol_flow.html",
    
    "relUrl": "/protocol_flow.html"
  },"36": {
    "doc": "Protocol Flow",
    "title": "Table of contents",
    "content": ". | Overview | Message Buffers | Reliable Delivery . | Outgoing Flow | Incoming Flow | . | Session Lifecycle | Handshake Sequence | Data Exchange | Binary Header Format | Payload Types | ACK Format | UUID Wire Format | Port Forwarding | Protocol Constants | Implementation Notes | . ",
    "url": "/protocol_flow.html#table-of-contents",
    
    "relUrl": "/protocol_flow.html#table-of-contents"
  },"37": {
    "doc": "Protocol Flow",
    "title": "Overview",
    "content": "This document describes the protocol flow for AWS SSM Session Manager WebSocket communication, based on analysis of the AWS session-manager-plugin. ",
    "url": "/protocol_flow.html#overview",
    
    "relUrl": "/protocol_flow.html#overview"
  },"38": {
    "doc": "Protocol Flow",
    "title": "Message Buffers",
    "content": "Reliable message delivery uses two buffers: . | Buffer | Type | Capacity | Purpose | . | OutgoingMessageBuffer | LinkedList | 10,000 | Messages waiting for ACK | . | IncomingMessageBuffer | HashMap | 10,000 | Out-of-order messages | . RTT Tracking (Jacobson/Karels algorithm, RFC 6298): . | RoundTripTime - Smoothed RTT estimate | RoundTripTimeVariation - RTT variance | RetransmissionTimeout - Adaptive timeout | . ",
    "url": "/protocol_flow.html#message-buffers",
    
    "relUrl": "/protocol_flow.html#message-buffers"
  },"39": {
    "doc": "Protocol Flow",
    "title": "Reliable Delivery",
    "content": "Outgoing Flow . flowchart LR A[Send Data] --&gt; B[Add to Buffer] B --&gt; C[Send via WebSocket] C --&gt; D{ACK Received?} D --&gt;|Yes| E[Remove from Buffer] D --&gt;|No| F[Timeout 200ms] F --&gt; C . Incoming Flow . flowchart TD A[Receive Message] --&gt; B{seq vs expected?} B --&gt;|seq == expected| C[Process + ACK] B --&gt;|seq &gt; expected| D[Buffer + ACK] B --&gt;|seq &lt; expected| E[Duplicate: Drop silently] C --&gt; F[Increment expected] F --&gt; G{Buffer has next?} G --&gt;|Yes| C G --&gt;|No| H[Done] . Critical: Do NOT ACK duplicates. The sender tracks unacked messages and will stop retrying when duplicates aren’t acknowledged. ",
    "url": "/protocol_flow.html#reliable-delivery",
    
    "relUrl": "/protocol_flow.html#reliable-delivery"
  },"40": {
    "doc": "Protocol Flow",
    "title": "Session Lifecycle",
    "content": "flowchart TD A[Connect WebSocket] --&gt; B[Send OpenDataChannelInput] B --&gt; C{Agent Type?} C --&gt;|Modern| D[Receive HandshakeRequest] C --&gt;|Legacy| E[Receive Output directly] D --&gt; F[Send HandshakeResponse] F --&gt; G[Receive HandshakeComplete] G --&gt; H[Session Ready] E --&gt; H H --&gt; I[Data Exchange] I --&gt; J[channel_closed] . ",
    "url": "/protocol_flow.html#session-lifecycle",
    
    "relUrl": "/protocol_flow.html#session-lifecycle"
  },"41": {
    "doc": "Protocol Flow",
    "title": "Handshake Sequence",
    "content": "sequenceDiagram participant C as Client participant A as Agent Note over C,A: Modern Agents v2.3.722+ A-&gt;&gt;C: HandshakeRequest C-&gt;&gt;A: ACK C-&gt;&gt;A: HandshakeResponse A-&gt;&gt;C: ACK A-&gt;&gt;C: HandshakeComplete C-&gt;&gt;A: ACK Note over C,A: Session Ready . ",
    "url": "/protocol_flow.html#handshake-sequence",
    
    "relUrl": "/protocol_flow.html#handshake-sequence"
  },"42": {
    "doc": "Protocol Flow",
    "title": "Data Exchange",
    "content": "sequenceDiagram participant C as Client participant A as Agent loop Interactive Shell C-&gt;&gt;A: input_stream_data A-&gt;&gt;C: ACK A-&gt;&gt;C: output_stream_data C-&gt;&gt;A: ACK end . ",
    "url": "/protocol_flow.html#data-exchange",
    
    "relUrl": "/protocol_flow.html#data-exchange"
  },"43": {
    "doc": "Protocol Flow",
    "title": "Binary Header Format",
    "content": "| Offset | Size | Field | Description | . | 0 | 4 | HeaderLength | Always 116 | . | 4 | 32 | MessageType | e.g. “input_stream_data” | . | 36 | 4 | SchemaVersion | Always 1 | . | 40 | 8 | CreatedDate | Unix millis | . | 48 | 8 | SequenceNumber | Message sequence | . | 56 | 8 | Flags | SYN=1, FIN=2 | . | 64 | 16 | MessageId | UUID (byte-swapped) | . | 80 | 32 | PayloadDigest | SHA-256 of payload | . | 112 | 4 | PayloadType | 1=Output, 5=Handshake, etc. | . | 116 | 4 | PayloadLength | Payload size | . ",
    "url": "/protocol_flow.html#binary-header-format",
    
    "relUrl": "/protocol_flow.html#binary-header-format"
  },"44": {
    "doc": "Protocol Flow",
    "title": "Payload Types",
    "content": "| Type | Name | Direction | Description | . | 1 | Output | Agent→Client | Shell stdout | . | 2 | Error | Agent→Client | Error message | . | 3 | Size | Client→Agent | Terminal resize | . | 5 | HandshakeRequest | Agent→Client | Handshake initiation | . | 6 | HandshakeResponse | Client→Agent | Handshake reply | . | 7 | HandshakeComplete | Agent→Client | Handshake done | . | 10 | Flag | Both | Control flags | . | 11 | StdErr | Agent→Client | Shell stderr | . | 12 | ExitCode | Agent→Client | Process exit | . ",
    "url": "/protocol_flow.html#payload-types",
    
    "relUrl": "/protocol_flow.html#payload-types"
  },"45": {
    "doc": "Protocol Flow",
    "title": "ACK Format",
    "content": "ACK messages have specific fixed values: . | Field | Value | . | SequenceNumber | 0 (always) | . | Flags | 3 (SYN | FIN) | . | MessageType | “acknowledge” | . Payload (JSON): . { \"AcknowledgedMessageType\": \"output_stream_data\", \"AcknowledgedMessageId\": \"uuid-string\", \"AcknowledgedMessageSequenceNumber\": 42, \"IsSequentialMessage\": true } . ",
    "url": "/protocol_flow.html#ack-format",
    
    "relUrl": "/protocol_flow.html#ack-format"
  },"46": {
    "doc": "Protocol Flow",
    "title": "UUID Wire Format",
    "content": "AWS uses non-standard byte order: . Standard: [MSB 0-7] [LSB 8-15] AWS Wire: [LSB 8-15] [MSB 0-7] . ",
    "url": "/protocol_flow.html#uuid-wire-format",
    
    "relUrl": "/protocol_flow.html#uuid-wire-format"
  },"47": {
    "doc": "Protocol Flow",
    "title": "Port Forwarding",
    "content": "sequenceDiagram participant L as Local App participant C as Client participant A as Agent participant T as Target L-&gt;&gt;C: TCP Connect C-&gt;&gt;A: Flag SYN A-&gt;&gt;T: TCP Connect A-&gt;&gt;C: Flag SYN loop Data Transfer L-&gt;&gt;C: Data C-&gt;&gt;A: input_stream_data A-&gt;&gt;T: Data T-&gt;&gt;A: Data A-&gt;&gt;C: output_stream_data C-&gt;&gt;L: Data end L--xC: TCP Close C-&gt;&gt;A: Flag FIN . ",
    "url": "/protocol_flow.html#port-forwarding",
    
    "relUrl": "/protocol_flow.html#port-forwarding"
  },"48": {
    "doc": "Protocol Flow",
    "title": "Protocol Constants",
    "content": "| Constant | Value | . | Header Length | 116 bytes | . | Schema Version | 1 | . | Max Payload | 64 KB | . | ACK Timeout | ~200ms | . | Max Retries | 3000 (5 min) | . | Buffer Capacity | 10,000 messages | . ",
    "url": "/protocol_flow.html#protocol-constants",
    
    "relUrl": "/protocol_flow.html#protocol-constants"
  },"49": {
    "doc": "Protocol Flow",
    "title": "Implementation Notes",
    "content": ". | ACK Only Non-Duplicates: seq &lt; expected → drop silently | ACK Immediately: Don’t wait for processing | UUID Byte Swap: LSB first (8-15), MSB second (0-7) | PayloadDigest: SHA-256 of payload only | OpenDataChannelInput: Send as TEXT, not binary | Respect pause_publication: Stop sending immediately | . ",
    "url": "/protocol_flow.html#implementation-notes",
    
    "relUrl": "/protocol_flow.html#implementation-notes"
  },"50": {
    "doc": "Python",
    "title": "Python Bindings",
    "content": "Async Python bindings via PyO3 with full type hints. ",
    "url": "/python.html#python-bindings",
    
    "relUrl": "/python.html#python-bindings"
  },"51": {
    "doc": "Python",
    "title": "Table of contents",
    "content": ". | Installation | Quick Start | Session Manager | Context Manager | Interactive Shell | Multiple Sessions | Session Types | Type Hints | . ",
    "url": "/python.html#table-of-contents",
    
    "relUrl": "/python.html#table-of-contents"
  },"52": {
    "doc": "Python",
    "title": "Installation",
    "content": "pip install aws-ssm-bridge . ",
    "url": "/python.html#installation",
    
    "relUrl": "/python.html#installation"
  },"53": {
    "doc": "Python",
    "title": "Quick Start",
    "content": "import asyncio from aws_ssm_bridge import SessionManager async def main(): # Create session manager manager = await SessionManager.new() # Use context manager for automatic cleanup async with await manager.start_session(target=\"i-0123456789abcdef0\") as session: await session.send(b\"whoami\\n\") async for chunk in await session.output(): print(chunk.decode(), end=\"\") asyncio.run(main()) . ",
    "url": "/python.html#quick-start",
    
    "relUrl": "/python.html#quick-start"
  },"54": {
    "doc": "Python",
    "title": "Session Manager",
    "content": "The SessionManager handles AWS authentication and session lifecycle: . import asyncio from aws_ssm_bridge import SessionManager async def main(): # Create manager (loads AWS credentials from default chain) manager = await SessionManager.new() # Start session with options session = await manager.start_session( target=\"i-0123456789abcdef0\", region=\"us-west-2\", # Optional session_type=\"standard_stream\", # Optional reason=\"Debugging issue #123\", # Optional (for audit) ) # Wait for session to be ready if await session.wait_for_ready(timeout_secs=30.0): await session.send(b\"hostname\\n\") async for chunk in await session.output(): print(chunk.decode(), end=\"\") # Always terminate when done await session.terminate() asyncio.run(main()) . ",
    "url": "/python.html#session-manager",
    
    "relUrl": "/python.html#session-manager"
  },"55": {
    "doc": "Python",
    "title": "Context Manager",
    "content": "Use the async context manager for automatic cleanup: . async with await manager.start_session(target=\"i-xxx\") as session: await session.send(b\"ls -la\\n\") async for chunk in await session.output(): print(chunk.decode(), end=\"\") # Session automatically terminated on exit . ",
    "url": "/python.html#context-manager",
    
    "relUrl": "/python.html#context-manager"
  },"56": {
    "doc": "Python",
    "title": "Interactive Shell",
    "content": "Full terminal support with raw mode, resize, and signal handling: . import asyncio from aws_ssm_bridge import InteractiveShell, InteractiveConfig, run_shell async def main(): # Option 1: Quick one-liner await run_shell(\"i-0123456789abcdef0\") # Option 2: Full control config = InteractiveConfig( show_banner=True, send_initial_size=True, forward_signals=True, ) shell = InteractiveShell(config) await shell.connect(\"i-0123456789abcdef0\") await shell.run() # Blocks until Ctrl+D asyncio.run(main()) . Features: . | Raw terminal mode (no echo, immediate input) | Terminal resize detection (SIGWINCH) | Signal forwarding (Ctrl+C, Ctrl+D, Ctrl+Z) | Automatic terminal restoration on exit/crash | . ",
    "url": "/python.html#interactive-shell",
    
    "relUrl": "/python.html#interactive-shell"
  },"57": {
    "doc": "Python",
    "title": "Multiple Sessions",
    "content": "Run commands on multiple instances concurrently: . import asyncio from aws_ssm_bridge import SessionManager async def run_command(manager, instance_id: str, command: str) -&gt; str: async with await manager.start_session(target=instance_id) as session: await session.send(f\"{command}\\n\".encode()) output = [] async for chunk in await session.output(): output.append(chunk.decode()) if len(output) &gt; 10: break return \"\".join(output) async def main(): manager = await SessionManager.new() instances = [\"i-aaa\", \"i-bbb\", \"i-ccc\"] results = await asyncio.gather(*[ run_command(manager, i, \"hostname\") for i in instances ], return_exceptions=True) for inst, result in zip(instances, results): if isinstance(result, Exception): print(f\"{inst}: ERROR - {result}\") else: print(f\"{inst}: {result.strip()}\") asyncio.run(main()) . ",
    "url": "/python.html#multiple-sessions",
    
    "relUrl": "/python.html#multiple-sessions"
  },"58": {
    "doc": "Python",
    "title": "Session Types",
    "content": "AWS SSM Session Manager supports 3 session types: . # Shell session (default) - standard interactive shell shell = await manager.start_session( target=\"i-xxx\", session_type=\"standard_stream\", ) # Port forwarding session (AWS-StartPortForwardingSession) port = await manager.start_session( target=\"i-xxx\", session_type=\"port\", parameters={\"portNumber\": [\"3306\"], \"localPortNumber\": [\"13306\"]}, ) # Interactive commands (AWS-StartInteractiveCommand) cmd = await manager.start_session( target=\"i-xxx\", session_type=\"interactive_commands\", parameters={\"command\": [\"top\"]}, ) . For custom documents like AWS-StartSSHSession or AWS-StartPortForwardingSessionToRemoteHost: . # SSH over Session Manager ssh = await manager.start_session( target=\"i-xxx\", document_name=\"AWS-StartSSHSession\", parameters={\"portNumber\": [\"22\"]}, ) # Port forward through bastion to RDS rds = await manager.start_session( target=\"i-bastion\", document_name=\"AWS-StartPortForwardingSessionToRemoteHost\", parameters={ \"host\": [\"mydb.cluster-xxx.us-east-1.rds.amazonaws.com\"], \"portNumber\": [\"3306\"], \"localPortNumber\": [\"13306\"], }, ) . ",
    "url": "/python.html#session-types",
    
    "relUrl": "/python.html#session-types"
  },"59": {
    "doc": "Python",
    "title": "Type Hints",
    "content": "Full .pyi stubs are included for IDE autocomplete: . from aws_ssm_bridge import SessionManager, Session, OutputStream async def example(manager: SessionManager) -&gt; None: session: Session = await manager.start_session(target=\"i-xxx\") stream: OutputStream = await session.output() async for chunk in stream: data: bytes = chunk print(data.decode()) . ",
    "url": "/python.html#type-hints",
    
    "relUrl": "/python.html#type-hints"
  },"60": {
    "doc": "Python",
    "title": "Python",
    "content": " ",
    "url": "/python.html",
    
    "relUrl": "/python.html"
  },"61": {
    "doc": "Security",
    "title": "Security",
    "content": "Threat model and security implementation details. ",
    "url": "/security.html",
    
    "relUrl": "/security.html"
  },"62": {
    "doc": "Security",
    "title": "Table of contents",
    "content": ". | Design Principles | Threat Model | Credential Handling | Rate Limiting . | Default Limits | . | SSRF Protection | Deployment Checklist | . ",
    "url": "/security.html#table-of-contents",
    
    "relUrl": "/security.html#table-of-contents"
  },"63": {
    "doc": "Security",
    "title": "Design Principles",
    "content": ". | Memory safety - #![forbid(unsafe_code)] | AWS transport security - All SSM traffic encrypted via TLS (WSS) | Input validation - Defensive parsing throughout | Rate limiting - Built-in DoS protection | . ",
    "url": "/security.html#design-principles",
    
    "relUrl": "/security.html#design-principles"
  },"64": {
    "doc": "Security",
    "title": "Threat Model",
    "content": "| Threat | Mitigation | . | Message tampering | SHA-256 digest validation | . | Credential leakage | Redacted Debug impls, URL sanitization | . | Replay attacks | Sequence number tracking | . | DoS (large messages) | 10MB max payload | . | DoS (message flood) | Rate limiting (configurable) | . | SSRF | Strict AWS endpoint validation | . | MITM | TLS required (WSS only) | . ",
    "url": "/security.html#threat-model",
    
    "relUrl": "/security.html#threat-model"
  },"65": {
    "doc": "Security",
    "title": "Credential Handling",
    "content": "Credentials are automatically sanitized: . | Session tokens skipped in tracing spans | URLs sanitized to remove query parameters in logs | Custom Debug impls redact sensitive fields | . ",
    "url": "/security.html#credential-handling",
    
    "relUrl": "/security.html#credential-handling"
  },"66": {
    "doc": "Security",
    "title": "Rate Limiting",
    "content": "Token bucket rate limiting: . use aws_ssm_bridge::{RateLimiter, RateLimitConfig}; let limiter = RateLimiter::new(RateLimitConfig { tokens_per_second: 100.0, bucket_size: 50, ..Default::default() }); . Default Limits . | Limit | Value | . | Max payload size | 10 MB | . | Max decompressed size | 100 MB | . | Buffer capacity | 10,000 messages | . ",
    "url": "/security.html#rate-limiting",
    
    "relUrl": "/security.html#rate-limiting"
  },"67": {
    "doc": "Security",
    "title": "SSRF Protection",
    "content": "URL validation ensures only AWS SSM endpoints are allowed: . wss://*.ssmmessages.{region}.amazonaws.com wss://*.ssmmessages.{region}.amazonaws.com.cn . Prevents SSRF attacks where a malicious server might redirect connections. ",
    "url": "/security.html#ssrf-protection",
    
    "relUrl": "/security.html#ssrf-protection"
  },"68": {
    "doc": "Security",
    "title": "Deployment Checklist",
    "content": ". | Use environment variables or secrets manager for credentials | Enable CloudTrail logging for SSM API calls | Use VPC endpoints where possible | Set appropriate idle_timeout and max_duration | Monitor metrics for anomalies | Keep dependencies updated (cargo audit) | . ",
    "url": "/security.html#deployment-checklist",
    
    "relUrl": "/security.html#deployment-checklist"
  }
}
