Sync fork with upstream LittleProxy/LittleProxy (resolve open Dependabot alerts)

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+- package-ecosystem: maven
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule: 
+    interval: daily
+  open-pull-requests-limit: 10

.github/workflows/main.yml

@@ -0,0 +1,84 @@
+# This workflow will build a Java project with Maven, and cache/restore any dependencies to improve the workflow execution time
+# For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-maven
+
+name: Java CI with Maven
+
+on:
+  push:
+    branches: [ main ]
+    paths-ignore:
+      - '.idea/**'
+      - '.run/**'
+      - '**/*.md'
+      - 'src/site/**'
+      - '**/.editorconfig'
+      - '**/.gitattributes'
+      - '**/.gitignore'
+      - '/*.txt'
+      - '/*.bash'
+      - 'release'
+  pull_request:
+    paths-ignore:
+      - '.idea/**'
+      - '.run/**'
+      - '**/*.md'
+      - 'src/site/**'
+      - '**/.editorconfig'
+      - '**/.gitattributes'
+      - '**/.gitignore'
+      - '/*.txt'
+      - '/*.bash'
+      - 'release'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        platform: [ubuntu-latest, macos-latest, windows-latest]
+      fail-fast: false
+
+    runs-on: ${{ matrix.platform }}
+    timeout-minutes: 7
+
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up JDK 17
+        uses: actions/setup-java@v6
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+          cache: maven
+      - name: Check Java
+        run: java -version
+      - name: Check Maven
+        run: mvn --batch-mode --version
+      - name: Compile code
+        run: mvn --batch-mode compile
+      - name: Branch name [env]
+        run: echo running on branch ${GITHUB_REF##*/}
+      - name: Run smoke tests
+        run: mvn --batch-mode package -Psmoke-test
+      - name: Run slow tests
+        if: success()
+        run: mvn --batch-mode package -Pslow-tests
+
+      - name: Generate Maven test report
+        if: failure()
+        run: mvn --batch-mode surefire-report:report-only
+      - name: Upload test report
+        uses: actions/upload-artifact@v7
+        if: failure()
+        with:
+          name: test-report-${{matrix.platform}}
+          retention-days: 5
+          path: |
+            target/surefire-reports
+            target/site
+            target/*.hprof
+            target/*.txt
+            target/*.jks
+            target/*_cert*

.gitignore

@@ -1,4 +1,3 @@
-log.txt
 *.swp
 *.settings
 *.classpath
@@ -9,10 +8,13 @@ log.txt
 *.DS_Store
 *.orig
 target/
-.idea/
+dependency-reduced-pom.xml
 jmeter.log
 lib/
 LittleProxy.pro
 /bin
-/*.jks
 performance/site/
+.claude/settings.local.json
+/logs
+/.opencode
+/.sisyphus

.run/tests.run.xml

@@ -0,0 +1,19 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="tests" type="JUnit" factoryName="JUnit">
+    <module name="littleproxy.test" />
+    <extension name="coverage">
+      <pattern>
+        <option name="PATTERN" value="org.littleshoot.proxy.*" />
+        <option name="ENABLED" value="true" />
+      </pattern>
+    </extension>
+    <option name="PACKAGE_NAME" value="org.littleshoot.proxy" />
+    <option name="MAIN_CLASS_NAME" value="" />
+    <option name="METHOD_NAME" value="" />
+    <option name="TEST_OBJECT" value="package" />
+    <option name="VM_PARAMETERS" value="-ea -Xmx128m" />
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>

AGENTS.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+LittleProxy is a high-performance HTTP/HTTPS proxy library written on top of Netty. 
+It is consumed as an embedded library (`io.github.littleproxy:littleproxy`) and can also run as a standalone 
+executable via the shaded jar (`Launcher` main class).
+
+The active fork is maintained at https://github.com/LittleProxy/LittleProxy.
+
+## Build & Test Commands
+
+- Build & run all tests: `mvn test`
+- Package (produces the shaded runnable jar): `mvn clean package`
+- Skip tests while packaging: `mvn clean package -DskipTests`
+- Smoke tests only (fast subset, excludes `slow-test` tag): `mvn package -Psmoke-test`
+- Slow tests only (tagged `@Tag("slow-test")`): `mvn package -Pslow-tests`
+- Single test class: `mvn test -Dtest=MitmProxyTest`
+- Single test method: `mvn test -Dtest=MitmProxyTest#testProxyConnects`
+- Run the shaded jar locally: `./run.bash --server --config ./config/littleproxy.properties` (wraps `mvn package -Dmaven.test.skip=true` + `java -jar`)
+
+CI (`.github/workflows/main.yml`) runs `-Psmoke-test` then `-Pslow-tests` on Ubuntu/macOS/Windows with JDK 17.
+
+## Toolchain Constraints
+
+- **Main source targets Java 11** (`<release>11</release>`); **tests compile with Java 17** (`compile-tests-with-java17` execution). New main-source code must not use language features newer than Java 11.
+- Source is auto-formatted by **Spotless (google-java-format 1.28.0)** in the `compile` phase — it rewrites files on every build. Don't hand-align imports; just run the build.
+- **ErrorProne** runs during compilation with `-Xep:MissingSummary:OFF -Xep:JdkObsolete:OFF -Xep:ReferenceEquality:OFF -Xep:OperatorPrecedence:OFF`. Other checks are active.
+- `maven-enforcer-plugin` bans `junit:junit` and `org.hamcrest:hamcrest-core` — use JUnit Jupiter + AssertJ.
+
+## High-Level Architecture
+
+The proxy is built around two mirror Netty channel handlers and a small state machine.
+
+- **`DefaultHttpProxyServer`** (`impl/`) — bootstrap/entry point; owns the `ServerGroup` (shared Netty event loops), `HttpFiltersSource`, optional `MitmManager`, `ChainedProxyManager`, and `ProxyAuthenticator`. `HttpProxyServerBootstrap` is the fluent builder users interact with.
+- **`ClientToProxyConnection`** (`impl/`) — one per inbound client channel. Decodes HTTP requests, runs the filter chain, resolves/reuses a per-(host,port) `ProxyToServerConnection`, and writes responses back to the client. Also handles `CONNECT` (tunnel vs. MITM branch) and proxy auth.
+- **`ProxyToServerConnection`** (`impl/`) — one per upstream target. Drives `ConnectionFlow` during setup, then proxies request/response chunks. Caches chained-proxy fallback state.
+- **`ConnectionFlow` / `ConnectionFlowStep`** (`impl/`) — ordered async step machine used to set up outbound connections: `ConnectChannel` → optional chained-proxy handshake (HTTP CONNECT / SOCKS4 / SOCKS5) → optional `StartTunneling` or `EncryptChannel` (MITM) → `RespondCONNECTSuccessful` → `MitmEncryptClientChannel`. Each step returns a Netty `Future` and advances via callbacks.
+- **`ProxyConnection`** (`impl/`) — abstract base for both connections; owns the `ConnectionState` transitions (`AWAITING_INITIAL`, `AWAITING_CHUNK`, `CONNECTING`, `HANDSHAKING`, `NEGOTIATING_CONNECT`, `AWAITING_PROXY_AUTHENTICATION`, `DISCONNECT_REQUESTED`, `DISCONNECTED`). Saturation callbacks implement backpressure (pause client reads when any upstream is saturated, and vice versa).
+- **`HttpFilters` / `HttpFiltersSource`** (top-level package) — primary extension point. A new `HttpFilters` instance is created per request via `filterRequest(...)`. Callback order (request → server connect → response) is documented in `LittleProxy_Request_Handling_Architecture.md`; returning a non-null `HttpResponse` from `clientToProxyRequest`/`proxyToServerRequest` short-circuits the request.
+- **`MitmManager` + `SslEngineSource`** — supply `SSLEngine`s for HTTPS interception. The in-tree `extras/SelfSignedMitmManager` is demo-grade; production setups typically plug in `LittleProxy-mitm` or the BrowserMob `mitm` module (see README).
+- **`ChainedProxyManager` / `ChainedProxy`** — per-request upstream proxy selection. Returning `ChainedProxyAdapter.FALLBACK_TO_DIRECT_CONNECTION` or an empty queue fails over to a direct connection; otherwise connection failures walk the queue.
+- **Netty pipelines** — client-side: `HAProxyMessageDecoder?` → `HttpRequestDecoder` → optional `HttpObjectAggregator` → monitors → `IdleStateHandler` → `ClientToProxyConnection`. Server-side mirrors this with `HttpRequestEncoder` / `HeadAwareHttpResponseDecoder` plus optional `GlobalTrafficShapingHandler` for throttling. When a `CONNECT` tunnel is established (without MITM), HTTP codecs are removed and data flows as raw bytes via `readRaw`/`write`.
+- **`extras/`** contains production-adjacent but optional implementations (`ActivityLogger`, `LogFormat`, `SelfSignedMitmManager`, `HAProxyMessageEncoder`, `TrustingTrustManager`). Core must not depend on `extras`.
+
+For diagrams and the full lifecycle of CONNECT/MITM/filter callbacks, see `LittleProxy_Request_Handling_Architecture.md`.
+
+## Testing Notes
+
+- Always use SLF4J (`org.slf4j.Logger`/`LoggerFactory`) for logging, not log4j directly — this is the logging API used throughout the codebase.
+- Tests are JUnit Jupiter + AssertJ + Mockito; Jetty and WireMock are used as real backends (do not mock them away).
+- Long-running or timing-sensitive tests are marked `@Tag("slow-test")` and excluded from the default/smoke profile.
+- Integration tests start real proxy instances on ephemeral ports; prefer extending `AbstractProxyTest` / `BaseProxyTest` / `BaseChainedProxyTest` rather than duplicating setup.
+- Test resources include keystores and `log4j.xml` under `src/test/resources/`.
+- Prefer `final` fields for test fixtures (e.g. `private final Foo foo = mock();`) over non-final fields assigned in `@BeforeEach`.
+- Prefer initializing fields inline at declaration over assigning them in `@BeforeEach`, when possible (e.g. only fall back to `@BeforeEach` when a value depends on another mock's stubbing or on a checked exception).
+- Never use `any()`/`any(Class)` in a `verify(...)` clause — pass the actual expected argument instead, e.g. `verify(throwingTracker).serverDisconnected(fullFlowContext, hostAddress);` not `verify(throwingTracker).serverDisconnected(any(), any());`. `any()` in `verify` only checks that some call happened, not that it happened with the right arguments.
+- Avoid reflection to reach a private field/method from a test. Best: test through the class's public API. If that's not practical, widen the member to package-private (test class lives in the same package) rather than reaching in via reflection — less magic, and the IDE/compiler catch renames.
+
+## Release
+
+Release steps (version bumps in `pom.xml` + `README.md`, `deploy.bash`, tag, publish on Sonatype Central) are documented in `CONTRIBUTING.md`. Do not bump versions unless a release is being cut.

CLAUDE.md

@@ -0,0 +1,2 @@
+# CLAUDE.md
+@AGENTS.md

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+
+Contribution guide for LittleProxy
+
+## Project scope
+
+LittleProxy is intended to be a LITTLE library, not a kitchen-sink proxy with every conceivable feature.
+Before starting work on a new feature, please discuss it first in
+[GitHub Discussions](https://github.com/LittleProxy/LittleProxy/discussions) or as a
+[GitHub Issue](https://github.com/LittleProxy/LittleProxy/issues), so we can agree whether it fits the
+project's scope before you invest time implementing it.
+
+If you need a richer feature set, consider [BrowserUp Proxy](https://github.com/valfirst/browserup-proxy),
+which is built on top of LittleProxy and provides more functionality.
+
+## How to start
+
+    git clone git@github.com:LittleProxy/LittleProxy.git
+    cd LittleProxy
+    mvn test
+
+## Release
+
+* Update the release notes (file RELEASE_NOTES.md)
+* Change version in the pom.xml file (e.g. "2.4.5-SNAPSHOT" -> "2.4.5") 
+* Change version in README.md (e.g. "2.4.4" -> "2.4.5")
+* Run `mvn clean install`
+* Run `deploy.bash` (takes a while, showing "Waiting until Deployment **** is published")
+* Log into https://central.sonatype.com/publishing/deployments and ensure that the deployment status is "Published".
+* Commit the changes (e.g. with message "release LittleProxy 2.4.5") and make sure the CI build passes
+* Run `git tag v2.4.5 && git push --tags`
+* Create a new release in GitHub (go to `https://github.com/LittleProxy/LittleProxy/releases/new`)
+* Update the version in the pom.xml file to the next SNAPSHOT version (e.g. "2.4.5" -> "2.4.6-SNAPSHOT").
+* Commit the pom.xml change (e.g. with commit message "working on LittleProxy 2.4.6")
+* Announce the release in https://groups.google.com/forum/#!forum/littleproxy2
+
+## How-to
+
+### Check the built JAR target version
+> mvn clean package -DskipTests
+> javap -verbose -classpath target/littleproxy-*SNAPSHOT.jar org.littleshoot.proxy.ProxyAuthenticator | grep "major"
+
+* major version: 55 -> Java 11
+* major version: 61 -> Java 17