aws / aws/session-manager-plugin

Support smux protocol v2 for flow-controlled port forwarding

Open
#145 0 comments 2 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
320
Forks
97
PR merge metrics
No merged PRs in 30d

Description

## Summary

Multiplexed port forwarding (`AWS-StartPortForwardingSession`) uses smux over the WebSocket data channel. Both `session-manager-plugin` and the SSM Agent currently negotiate smux protocol v1, which has no per-stream flow control. This means client tools have no signal for when the agent's receive/session-wide throughput cap (~500 kbps, see aws/amazon-ssm-agent#664) is being exceeded, other than the session stalling or being torn down mid-transfer.

smux v2 (supported by the `xtaci/smux` library already vendored here, via `smux.Config{Version: 2}`) adds a `cmdUPD` frame that acknowledges consumed bytes and advertises a receive window per stream. This would let clients pace writes based on real backpressure from the agent instead of guessing a fixed rate.

## Current behavior

- `muxportforwarding.go` constructs its smux session with `smux.DefaultConfig()` and only ever overrides `KeepAliveDisabled`; `Version` is left at the library default (1).
- The client→agent bridge loop paces itself with an unconditional `time.Sleep(time.Millisecond)` after every read/send cycle (`transferDataToServer`), which caps aggregate throughput to a fixed, non-configurable rate rather than reacting to actual buffer state.
- Downstream client implementations that also multiplex over smux (e.g. third-party SSM clients) have to replicate this same fixed-rate workaround, since there's no protocol-level backpressure signal to build on.

## Request

Consider negotiating smux v2 between `session-manager-plugin`/SSM Agent and connecting clients (with a version-negotiation or agent-version-gated fallback to v1 for compatibility), so that port-forwarding throughput can be governed by real flow control instead of a fixed sleep-based cap.

## Related

- aws/amazon-ssm-agent#664 — confirms the ~500 kbps-class throughput ceiling and that it's enforced service-side via a message-rate cap, independent of instance size.

Contributor guide

Open the contributing guide

Research direction

Start with muxportforwarding.go to inspect smux.Config construction and the transferDataToServer bridge loop, then review how session-manager-plugin and the SSM Agent negotiate protocol versions. Done means compatible clients can use smux v2 flow control while older agents or clients still have a defined v1 fallback, with throughput governed by the protocol rather than the fixed sleep.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.