byway 0.6.0__tar.gz

byway-0.6.0/.editorconfig

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

byway-0.6.0/.gitattributes

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+* text=auto eol=lf

byway-0.6.0/.github/workflows/build.yml

@@ -0,0 +1,195 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+name: Build
+on:
+  push:
+    branches: ["**"]
+    tags: ["v[0-9]*"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  #-----------------------------------------------------------------------------
+
+  Lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      # keep aligned with [tool.ruff] in pyproject.toml
+      - name: Check formatting
+        run: uvx --from 'ruff~=0.16.0' ruff format --check .
+
+      - name: Lint
+        run: uvx --from 'ruff~=0.16.0' ruff check .
+
+      - name: Check REUSE compliance
+        run: uvx reuse lint
+
+  #-----------------------------------------------------------------------------
+
+  Typecheck:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      # full history for hatch-vcs
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      # per OS: mypy narrows sys.platform checks to the host
+      - name: Type-check
+        run: uv run --locked mypy src
+
+  #-----------------------------------------------------------------------------
+
+  Build:
+    runs-on: ubuntu-latest
+    steps:
+      # full history for hatch-vcs
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      - name: Build project
+        run: uv build --no-sources
+
+      - name: Smoke-test wheel
+        run: |
+          uv run --isolated --no-project --with dist/*.whl python - <<'EOF'
+          import os
+          import byway
+          print(byway.__version__)
+          if os.environ["GITHUB_REF_TYPE"] == "tag":
+              expected = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+              assert byway.__version__ == expected, (byway.__version__, expected)
+          EOF
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  #-----------------------------------------------------------------------------
+
+  Test:
+    needs:
+      - Build
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      # Only the tests; byway comes from the wheel the Build job made.
+      # .gitattributes keeps the corpus and the tests at LF on Windows.
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          sparse-checkout: |
+            tests
+            pyproject.toml
+            .gitattributes
+          sparse-checkout-cone-mode: false
+
+      - name: Download artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: ${{ matrix.python }}
+
+      # The versions in uv.lock. byway's own dependencies, usernet among them,
+      # resolve from the wheel's metadata, as they do for users.
+      - name: Install wheel and test dependencies
+        run: |
+          uv venv
+          uv pip install "$(ls dist/*.whl)[keyring]" "usernet[testing]" pytest==9.1.1 pytest-asyncio==1.4.0 pytest-timeout==2.4.0 hypothesis==6.165.9 trustme==1.2.1
+
+      - name: Run tests
+        run: uv run --no-project pytest -q -m "not needs_gateway"
+
+  #-----------------------------------------------------------------------------
+
+  Release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    needs:
+      - Lint
+      - Typecheck
+      - Build
+      - Test
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create draft release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create "$GITHUB_REF_NAME" dist/*
+          --repo "$GITHUB_REPOSITORY"
+          --draft
+          --verify-tag
+          --generate-notes
+
+  #-----------------------------------------------------------------------------
+
+  PyPI:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    needs:
+      - Build
+      - Release
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/byway
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

byway-0.6.0/.gitignore

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.mypy_cache
+.pytest_cache
+.ruff_cache
+
+# Virtual environments
+.venv
+
+# other
+.hypothesis

byway-0.6.0/.python-version

@@ -0,0 +1 @@
+3.12

byway-0.6.0/CLAUDE.md

@@ -0,0 +1,23 @@
+# CLAUDE.md
+
+byway is a userspace client that speaks the Cisco AnyConnect VPN protocol: the tunnel
+terminates in an in-process TCP/IP stack (from `usernet`), exposed through SOCKS5 and a
+Python API.
+
+- Read [docs/DESIGN.md](docs/DESIGN.md) before architectural changes and respect its core
+  principles.
+- CLI options, profiles and the library API: [docs/MANUAL.md](docs/MANUAL.md).
+- Runtime behavior (idle timeout, reconnects, throughput): [docs/OPERATIONS.md](docs/OPERATIONS.md).
+- Gateway quirks and protocol facts: [docs/protocol.md](docs/protocol.md). Add anything
+  learned the hard way there.
+- Anything not specific to this VPN protocol belongs in `../usernet`, not here.
+
+@docs/DEVELOPMENT.md
+
+## Documentation rules
+
+- Keep the README short: what byway is and a working usage example. Everything else goes
+  into `docs/`.
+- A change that affects design, usage or behavior updates the matching document in the same
+  change.
+- DESIGN.md is kept current and carries no project history.

byway-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contribution guidelines
+
+I'm open to receiving bug reports, but I'm not really interested in anything else at this point. You can still bring forward whatever you want to say, just manage your expectations accordingly.

byway-0.6.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright (C) 2026 by René de Hesselle
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

byway-0.6.0/LICENSES/0BSD.txt

@@ -0,0 +1,5 @@
+Copyright (C) 2026 by René de Hesselle
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

byway-0.6.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: byway
+Version: 0.6.0
+Summary: Userspace client that speaks the Cisco AnyConnect VPN protocol, with an in-process TCP/IP stack
+Project-URL: Homepage, https://github.com/dehesselle/byway
+Project-URL: Repository, https://github.com/dehesselle/byway
+Author-email: René de Hesselle <dehesselle@web.de>
+License-Expression: 0BSD
+License-File: LICENSE
+License-File: LICENSES/0BSD.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.12
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: platformdirs>=4
+Requires-Dist: usernet[httpx]>=0.7
+Provides-Extra: keyring
+Requires-Dist: keyring>=25; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# byway
+
+> __Byway__ · _English noun_
+>
+> A secondary road or path, away from the main route.
+
+byway is a userspace client that speaks the Cisco AnyConnect VPN protocol. No tun device, no
+virtual adapter, no routing changes, no administrator rights: the tunnel and everything carried
+over it live inside the Python process. Access is through a local SOCKS5 proxy, so `ssh` and
+`curl` work unchanged, and an in-process API.
+
+Use it when you need to reach a REST API or SSH into a host inside a corporate VPN, but
+cannot, or would rather not, install a VPN client, change routing, or use admin rights. VPN
+access is scoped to one process rather than to the whole machine.
+
+## Install and run
+
+```console
+$ uv tool install byway
+$ byway probe vpn.corp.example          # what does this gateway ask for?
+$ byway up vpn.corp.example -u user --socks
+address   172.29.29.3/255.255.0.0
+mtu       1383
+routes    10.0.0.0/23
+socks5    127.0.0.1:1080
+```
+
+`byway up` prompts for the password and holds the tunnel open. From another terminal:
+
+```sh
+curl --socks5 127.0.0.1:1080 http://10.0.0.20/
+ssh -o ProxyCommand="byway nc --via 127.0.0.1:1080 %h %p" user@10.0.0.32
+```
+
+Saved profiles, other ways to pass the password, and certificate pinning are in the
+[manual](https://github.com/dehesselle/byway/blob/master/docs/MANUAL.md).
+
+## Use it from your own program
+
+```sh
+uv add byway
+```
+
+```python
+import byway
+
+async with byway.connect("vpn.corp.example", user, password) as vpn:
+    reader, writer = await vpn.open_connection("10.0.0.32", 22)
+
+    async with vpn.httpx_client() as http:
+        response = await http.get("http://10.0.0.20/v1/things")
+```
+
+## Caveats
+
+- Hosts are IP addresses, or names from a fixed table in the profile: there is no in-tunnel
+  DNS.
+- byway supports IPv4, TLS, outbound TCP and username/password authentication only.
+- Many organisations require a sanctioned VPN client, and byway bypasses posture assessment
+  (CSD/HostScan) entirely. Check that you are allowed to use it before you point it at a
+  corporate gateway.
+
+## Documentation
+
+- [docs/MANUAL.md](https://github.com/dehesselle/byway/blob/master/docs/MANUAL.md) — all commands, profiles, credentials, certificate pinning and the library API.
+- [docs/http-async.md](https://github.com/dehesselle/byway/blob/master/docs/http-async.md) — calling REST APIs from async code.
+- [docs/http-sync.md](https://github.com/dehesselle/byway/blob/master/docs/http-sync.md) — calling REST APIs from sync code.
+- [docs/OPERATIONS.md](https://github.com/dehesselle/byway/blob/master/docs/OPERATIONS.md) — runtime behavior: idle timeouts, reconnects, sessions, throughput, diagnostics.
+- [docs/DESIGN.md](https://github.com/dehesselle/byway/blob/master/docs/DESIGN.md) — architecture, core principles and deliberate omissions.
+- [docs/protocol.md](https://github.com/dehesselle/byway/blob/master/docs/protocol.md) — protocol notes and gateway observations.
+- [docs/throughput.md](https://github.com/dehesselle/byway/blob/master/docs/throughput.md) — throughput measurements.
+- [docs/DEVELOPMENT.md](https://github.com/dehesselle/byway/blob/master/docs/DEVELOPMENT.md) — building and testing.
+
+## AI disclosure
+
+Substantial parts of this code were generated with Sonnet 5.x/Opus 5.x. Generated code was tested, but not every line was reviewed in detail.
+
+## License
+
+[0BSD](https://github.com/dehesselle/byway/blob/master/LICENSES/0BSD.txt)

byway-0.6.0/README.md

@@ -0,0 +1,80 @@
+# byway
+
+> __Byway__ · _English noun_
+>
+> A secondary road or path, away from the main route.
+
+byway is a userspace client that speaks the Cisco AnyConnect VPN protocol. No tun device, no
+virtual adapter, no routing changes, no administrator rights: the tunnel and everything carried
+over it live inside the Python process. Access is through a local SOCKS5 proxy, so `ssh` and
+`curl` work unchanged, and an in-process API.
+
+Use it when you need to reach a REST API or SSH into a host inside a corporate VPN, but
+cannot, or would rather not, install a VPN client, change routing, or use admin rights. VPN
+access is scoped to one process rather than to the whole machine.
+
+## Install and run
+
+```console
+$ uv tool install byway
+$ byway probe vpn.corp.example          # what does this gateway ask for?
+$ byway up vpn.corp.example -u user --socks
+address   172.29.29.3/255.255.0.0
+mtu       1383
+routes    10.0.0.0/23
+socks5    127.0.0.1:1080
+```
+
+`byway up` prompts for the password and holds the tunnel open. From another terminal:
+
+```sh
+curl --socks5 127.0.0.1:1080 http://10.0.0.20/
+ssh -o ProxyCommand="byway nc --via 127.0.0.1:1080 %h %p" user@10.0.0.32
+```
+
+Saved profiles, other ways to pass the password, and certificate pinning are in the
+[manual](https://github.com/dehesselle/byway/blob/master/docs/MANUAL.md).
+
+## Use it from your own program
+
+```sh
+uv add byway
+```
+
+```python
+import byway
+
+async with byway.connect("vpn.corp.example", user, password) as vpn:
+    reader, writer = await vpn.open_connection("10.0.0.32", 22)
+
+    async with vpn.httpx_client() as http:
+        response = await http.get("http://10.0.0.20/v1/things")
+```
+
+## Caveats
+
+- Hosts are IP addresses, or names from a fixed table in the profile: there is no in-tunnel
+  DNS.
+- byway supports IPv4, TLS, outbound TCP and username/password authentication only.
+- Many organisations require a sanctioned VPN client, and byway bypasses posture assessment
+  (CSD/HostScan) entirely. Check that you are allowed to use it before you point it at a
+  corporate gateway.
+
+## Documentation
+
+- [docs/MANUAL.md](https://github.com/dehesselle/byway/blob/master/docs/MANUAL.md) — all commands, profiles, credentials, certificate pinning and the library API.
+- [docs/http-async.md](https://github.com/dehesselle/byway/blob/master/docs/http-async.md) — calling REST APIs from async code.
+- [docs/http-sync.md](https://github.com/dehesselle/byway/blob/master/docs/http-sync.md) — calling REST APIs from sync code.
+- [docs/OPERATIONS.md](https://github.com/dehesselle/byway/blob/master/docs/OPERATIONS.md) — runtime behavior: idle timeouts, reconnects, sessions, throughput, diagnostics.
+- [docs/DESIGN.md](https://github.com/dehesselle/byway/blob/master/docs/DESIGN.md) — architecture, core principles and deliberate omissions.
+- [docs/protocol.md](https://github.com/dehesselle/byway/blob/master/docs/protocol.md) — protocol notes and gateway observations.
+- [docs/throughput.md](https://github.com/dehesselle/byway/blob/master/docs/throughput.md) — throughput measurements.
+- [docs/DEVELOPMENT.md](https://github.com/dehesselle/byway/blob/master/docs/DEVELOPMENT.md) — building and testing.
+
+## AI disclosure
+
+Substantial parts of this code were generated with Sonnet 5.x/Opus 5.x. Generated code was tested, but not every line was reviewed in detail.
+
+## License
+
+[0BSD](https://github.com/dehesselle/byway/blob/master/LICENSES/0BSD.txt)

byway-0.6.0/REUSE.toml

@@ -0,0 +1,14 @@
+version = 1
+
+# Files that can't carry an SPDX comment, or shouldn't: docs stay clean when
+# rendered, the corpus is test input for the parsers, and uv.lock is
+# regenerated.
+[[annotations]]
+path = [
+    "**.md",
+    "tests/corpus/*.xml",
+    "uv.lock",
+    ".python-version",
+]
+SPDX-FileCopyrightText = "2026 René de Hesselle <dehesselle@web.de>"
+SPDX-License-Identifier = "0BSD"

byway-0.6.0/docs/DESIGN.md

@@ -0,0 +1,93 @@
+# byway design
+
+How byway is built and why. This is the standing design reference: keep it current when the
+design changes.
+
+## Architecture
+
+openconnect solves the same problem as byway by handing decapsulated IP packets to a tun
+device and letting the kernel do TCP. byway refuses that, so it has to terminate IP itself:
+the gateway hands us raw IP packets, and an in-process TCP/IP stack turns them back into
+streams.
+
+```text
+curl, ssh ──SOCKS5──┐
+                    ├─▶ usernet: TCP/IP stack, driver ──IpLink──▶ ReconnectingLink ──CSTP/TLS──▶ gateway
+your code ──API─────┘   (SOCKS5 server, stream bridge)            (this repository)
+```
+
+The TCP/IP stack, the driver, the SOCKS5 server and the transport bridge are not in this
+repository. They are [`usernet`](https://github.com/dehesselle/usernet), because none of
+that code knows what AnyConnect is and a second client — a Tailscale one — needed exactly the
+same half. What is left here is CSTP: authentication, the tunnel handshake, frame transport,
+and reconnection.
+
+The seam is `usernet.link.IpLink`: anything that can carry raw IPv4 packets and say what
+address it was assigned. `ReconnectingLink` is this project's implementation of it.
+
+## Core principles
+
+1. **No tun device, no routing changes, no administrator rights.** Everything carried over
+   the tunnel lives inside the Python process, so VPN access is scoped to that process.
+2. **Only the VPN protocol lives here.** Anything not specific to it belongs in `usernet`,
+   behind `IpLink`.
+3. **Every session ends with a logout.** Leaving `byway.connect()` closes the tunnel *and*
+   posts the logout, whatever went wrong. That is not housekeeping: gateways enforce
+   concurrent-session limits, and leaked sessions eventually lock you out of your own VPN
+   with nothing to point at.
+4. **Credentials never go in `argv` or in the config file.** Passwords come from stdin, the
+   environment, the keyring or a prompt ([MANUAL.md](MANUAL.md#credentials)).
+5. **One CSTP frame per TLS record.** A Cisco ASA hangs up on anything else; see
+   [protocol.md](protocol.md#one-frame-per-tls-record--mandatory). `--coalesce` exists for
+   experiments only and must never be the default.
+6. **Names come from the tunnel's host table or nowhere.** Falling back to the host's
+   resolver would send internal hostnames to whatever DNS the machine uses. A name is
+   resolved from a static table (the profile's `hosts`, `--add-host`, or `hosts=` in the
+   API) and refused otherwise, everywhere: SOCKS5, `http`, `nc` and the library. The table
+   is a `usernet.resolve.StaticResolver` on the driver, so every consumer gets the same
+   answer, and routing is checked against the address, not the name.
+7. **Streams are real stdlib streams, and backpressure reaches the peer.**
+   `StreamReader`'s high-water mark calls `pause_reading()`, which stops us draining the
+   stack, which shrinks the advertised window, which stops the far end sending — without a
+   queue anywhere in between.
+8. **SOCKS5 binds loopback unless told otherwise.** An unauthenticated proxy on a routable
+   address is an open door into the corporate network for anything that can reach the
+   machine.
+
+## Deliberate omissions
+
+- **No DNS client, a static host table only.** The gateway this was developed against
+  advertises no DNS servers at all, so there is nothing to ask, and the machines behind it
+  have fixed addresses. The table matches names exactly: no wildcards, no search domain, no
+  reverse lookups. Querying a DNS server would also need UDP, which byway does not carry. On
+  a gateway that does advertise DNS servers, a resolver using them could take the table's
+  place on the driver.
+- **No compression.** byway does not advertise `X-CSTP-Accept-Encoding`, so LZS, LZ4 and
+  deflate never need implementing. A compressed frame arriving anyway is a loud error.
+- **TLS only, no DTLS.** Everything rides the TLS connection.
+- **IPv4 only, outbound TCP only.**
+- **Username and password only.** SAML/SSO, client certificates and MFA challenges are
+  detected and reported clearly, but not supported.
+- **No posture assessment.** CSD/HostScan is bypassed entirely.
+
+## Reconnection
+
+`ReconnectingLink` rebuilds the tunnel when it ends, unless `reconnect=False`
+(`--no-reconnect`). Some gateways assign a fresh address on every connection. Sockets bound
+to the old address cannot survive that, so they are failed with an error saying exactly
+that, rather than left to hang. The tunnel and the SOCKS listener stay up.
+
+A gateway's `X-CSTP-Rekey-Method: ssl` is treated as `new-tunnel`, because Python's `ssl`
+cannot renegotiate ([protocol.md](protocol.md#cisco-asa--secure-client-515)).
+
+## Buffer size
+
+One connection cannot exceed `buffer ÷ RTT`, whatever the code does, so the default
+per-socket buffer is 1 MiB, raised with `--buffer KIB`. Bigger is not automatically better:
+past about 1 MiB the
+sender's bursts start overrunning queues below us and the returns go negative. The
+measurements are in [throughput.md](throughput.md).
+
+If a link ever needs more than this can give, `usernet`'s `NetworkBackend` protocol exists
+so a native stack could be dropped in. On a high-latency or policed link that would change
+nothing, because the limit is not the CPU.

byway-0.6.0/docs/DEVELOPMENT.md

@@ -0,0 +1,65 @@
+# Development
+
+Building and testing byway. The design is described in [DESIGN.md](DESIGN.md).
+
+byway uses Python 3.12 and [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync --dev
+```
+
+The version comes from git tags via hatch-vcs, so clone with full history.
+
+## Checks
+
+CI runs ruff and the REUSE check once on Ubuntu, mypy on Ubuntu and Windows, and pytest on
+Ubuntu and Windows with Python 3.12, 3.13 and 3.14. Run these before committing:
+
+```sh
+uvx --from 'ruff~=0.16.0' ruff check .
+uvx --from 'ruff~=0.16.0' ruff format --check .
+uvx reuse lint
+uv run mypy src
+uv run pytest -q -m "not needs_gateway"
+```
+
+- Ruff isn't a project dependency. `required-version` in `pyproject.toml` and the pin in
+  `.github/workflows/build.yml` are bumped together, once a new minor release's findings have
+  been reviewed.
+- CI tests the built wheel rather than the checkout, against the test dependency versions
+  pinned in `.github/workflows/build.yml`. Update those pins when `uv.lock` moves them.
+- The project is REUSE-compliant. New files start with the SPDX header that `reuse annotate`
+  writes; files that can't carry a comment get covered in `REUSE.toml`.
+
+## Releasing
+
+Pushing a tag `vX.Y.Z` runs the full workflow and, if every job passes, attaches the built
+sdist and wheel to a draft GitHub release and publishes them to PyPI. The build job checks that
+the wheel's `__version__` matches the tag. PyPI accepts the upload through trusted publishing,
+which requires a publisher on pypi.org for this repository, the workflow `build.yml` and the
+GitHub environment `pypi`. The draft release is published by hand.
+
+## usernet
+
+[`usernet`](https://github.com/dehesselle/usernet) is an ordinary dependency from PyPI. To
+try byway against a local checkout of it, install that into the venv with
+`uv pip install -e ../usernet`; the next `uv sync` puts the released version back.
+
+## How it is tested
+
+CSTP is what this repository is responsible for, and the ways a gateway can surprise you are
+what it tests:
+
+- **Codecs** (`tests/unit`): CSTP framing and the tunnel headers, auth XML against a corpus
+  of real gateway responses (`tests/corpus`), plus property-based tests feeding arbitrary
+  bytes into every parser and asserting that only declared parse errors escape.
+- **A fake CSTP gateway** (`tests/fakegw`) that serves the auth exchange, speaks framing,
+  injects faults, and terminates IP into a test peer — so `byway up` → SOCKS5 → a real HTTP
+  GET runs in CI with no VPN anywhere (`tests/integration`).
+- **Reconnection and rekey**, including the case that matters most: a gateway that assigns a
+  different address on reconnect, where every open socket has to fail with a reason rather
+  than hang.
+
+The stack's own test layers — the frozen-clock state machine, the virtual network, and
+conformance against a real Linux kernel over a tun device degraded with `netem` — live in
+`usernet` along with the code they cover.