chore: add CLAUDE.md and apply spotless formatting

coopernetes · claude · coopernetes · commit f0f2c6a1af2d · 2026-03-29T12:49:57.000-04:00
- CLAUDE.md: project context, architecture, build/test commands, Docker
  Compose usage, and configuration notes for AI-assisted development
- spotlessApply: reformat e2e test classes to palantir-java-format style

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,77 @@
+# jgit-proxy — Claude context
+
+Java rewrite of [FINOS git-proxy](https://github.com/finos/git-proxy) (Node.js). Proxies git push/fetch operations and enforces security/compliance checks.
+
+## Repository layout
+
+| Module | Purpose |
+|--------|---------|
+| `jgit-proxy-core` | Shared library: filter chain, JGit hooks, push store, provider model |
+| `jgit-proxy-server` | Standalone Jetty server (`GitProxyJettyApplication`) |
+
+## Architecture
+
+Two proxy modes, both configurable per-provider:
+
+- **Store-and-forward** (`/push/<provider>/<owner>/<repo>.git`) — JGit ReceivePack receives the push locally, runs a pre-receive hook chain (`AuthorEmailValidationHook` → `CommitMessageValidationHook` → `ValidationVerifierHook`), then `ForwardingPostReceiveHook` pushes upstream using the client's credentials.
+- **Transparent proxy** (`/proxy/<provider>/<owner>/<repo>.git`) — Jetty's `ProxyServlet` forwards the request; a servlet filter chain (`ParseGitRequestFilter` → `EnrichPushCommitsFilter` → validation filters) inspects the pack data before it reaches the upstream.
+
+## Reference implementation
+
+The Node.js original lives at `/home/tom/repos/git-proxy`. Refer to it for the Action/Step model, Sink interface, and filter chain patterns when porting features.
+
+## Build & test
+
+```bash
+./gradlew build              # compile + unit tests (no containers)
+./gradlew test               # unit tests only (e2e excluded)
+./gradlew e2eTest            # e2e tests — requires Docker/Podman
+./gradlew spotlessApply      # fix formatting (palantir-java-format)
+```
+
+Unit tests live under each module's `src/test/`. E2e tests are in `jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/` and tagged `@Tag("e2e")`.
+
+## Integration testing (manual)
+
+Use the shell scripts in the repo root against a running server (`./gradlew :jgit-proxy-server:run`):
+
+```bash
+test-push-pass.sh   # store-and-forward — valid commits
+test-push-fail.sh   # store-and-forward — commits that should be rejected
+test-proxy-pass.sh  # proxy mode — valid commits
+test-proxy-fail.sh  # proxy mode — commits that should be rejected
+```
+
+## Docker Compose
+
+```bash
+docker compose up -d          # jgit-proxy + Gitea (h2-mem database)
+bash docker/setup.sh          # one-time: create admin user + test repo in Gitea
+
+# Optional database backends:
+docker compose --profile postgres up -d   # swap git-proxy-local.yml for git-proxy-postgres.yml
+docker compose --profile mongo up -d      # swap git-proxy-local.yml for git-proxy-mongo.yml
+```
+
+Config override file mounted at `/app/conf/git-proxy-local.yml` inside the container. Templates in `docker/`.
+
+## Configuration
+
+`JettyConfigurationLoader` merges (lowest → highest priority):
+1. `git-proxy.yml` (classpath, shipped with jar) — defaults + GitHub/GitLab/Bitbucket providers
+2. `git-proxy-local.yml` (classpath, optional) — local overrides; put in `/app/conf/` for Docker
+3. `GITPROXY_*` environment variables
+
+Supported env vars: `GITPROXY_SERVER_PORT`, `GITPROXY_GITPROXY_BASEPATH`, `GITPROXY_PROVIDERS_<NAME>_ENABLED`.
+
+## Database backends
+
+Configured via `database.type` in YAML. Supported: `memory`, `h2-mem`, `h2-file`, `sqlite`, `postgres`, `mongo`.
+
+## Podman notes
+
+Always use fully qualified image names (e.g. `docker.io/eclipse-temurin:21-jre`). Podman on Fedora enforces short-name resolution and will error without a TTY if bare names are used.
+
+## Branch / PR target
+
+Default branch for PRs: **`jetty`**
diff --git a/jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/GitHelper.java b/jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/GitHelper.java
@@ -7,9 +7,8 @@
 import java.util.List;
 
 /**
- * Thin wrapper around the system {@code git} CLI for use in e2e tests. Mirrors the pattern in the
- * shell test scripts: each helper method maps directly to a sequence of git commands that those
- * scripts execute.
+ * Thin wrapper around the system {@code git} CLI for use in e2e tests. Mirrors the pattern in the shell test scripts:
+ * each helper method maps directly to a sequence of git commands that those scripts execute.
  */
 class GitHelper {
 
@@ -30,12 +29,10 @@ Path clone(String remoteUrl, String dirName) throws IOException, InterruptedExce
     }
 
     /**
-     * Sets the local git author identity for subsequent commits made in {@code repoDir}. Git
-     * includes credentials in the remote URL, so the author is the only identity that matters for
-     * validation purposes.
+     * Sets the local git author identity for subsequent commits made in {@code repoDir}. Git includes credentials in
+     * the remote URL, so the author is the only identity that matters for validation purposes.
      */
-    void setAuthor(Path repoDir, String name, String email)
-            throws IOException, InterruptedException {
+    void setAuthor(Path repoDir, String name, String email) throws IOException, InterruptedException {
         this.authorName = name;
         this.authorEmail = email;
         git(repoDir, "config", "user.name", name);
@@ -45,8 +42,7 @@ void setAuthor(Path repoDir, String name, String email)
     }
 
     /** Writes {@code content} to {@code fileName} in {@code repoDir} and stages it. */
-    void writeAndStage(Path repoDir, String fileName, String content)
-            throws IOException, InterruptedException {
+    void writeAndStage(Path repoDir, String fileName, String content) throws IOException, InterruptedException {
         Files.writeString(repoDir.resolve(fileName), content);
         git(repoDir, "add", fileName);
     }
@@ -76,10 +72,7 @@ boolean tryPush(Path repoDir) throws IOException, InterruptedException {
         return exitCode == 0;
     }
 
-    /**
-     * Returns the captured combined stdout+stderr from a push that is expected to fail, for
-     * assertion purposes.
-     */
+    /** Returns the captured combined stdout+stderr from a push that is expected to fail, for assertion purposes. */
     String pushOutput(Path repoDir) throws IOException, InterruptedException {
         String branch = currentBranch(repoDir);
         ProcessBuilder pb = buildGitCommand(repoDir, "push", "origin", branch);
diff --git a/jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/GiteaContainer.java b/jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/GiteaContainer.java
@@ -12,9 +12,8 @@
 /**
  * Testcontainers wrapper for a Gitea instance used as the upstream git server in e2e tests.
  *
- * <p>Starts Gitea with the install lock set (skips the setup wizard), creates an admin user via
- * the Gitea CLI, and initialises a public test repository ({@value #TEST_ORG}/{@value #TEST_REPO})
- * via the Gitea REST API.
+ * <p>Starts Gitea with the install lock set (skips the setup wizard), creates an admin user via the Gitea CLI, and
+ * initialises a public test repository ({@value #TEST_ORG}/{@value #TEST_REPO}) via the Gitea REST API.
  */
 @SuppressWarnings("resource")
 class GiteaContainer extends GenericContainer<GiteaContainer> {
@@ -54,11 +53,11 @@ URI getBaseUri() {
     }
 
     /**
-     * Creates the admin user by running the Gitea CLI inside the container. Must be called after
-     * the container has started.
+     * Creates the admin user by running the Gitea CLI inside the container. Must be called after the container has
+     * started.
      *
-     * <p>Uses {@code su-exec} (Alpine's privilege-dropper, always present in the Gitea image) to
-     * run as the {@code git} user — the Gitea binary refuses to start as root.
+     * <p>Uses {@code su-exec} (Alpine's privilege-dropper, always present in the Gitea image) to run as the {@code git}
+     * user — the Gitea binary refuses to start as root.
      */
     void createAdminUser() throws IOException, InterruptedException {
         var result = execInContainer(
@@ -69,44 +68,39 @@ void createAdminUser() throws IOException, InterruptedException {
                 "user",
                 "create",
                 "--admin",
-                "--username", ADMIN_USER,
-                "--password", ADMIN_PASSWORD,
-                "--email", ADMIN_EMAIL,
+                "--username",
+                ADMIN_USER,
+                "--password",
+                ADMIN_PASSWORD,
+                "--email",
+                ADMIN_EMAIL,
                 "--must-change-password=false");
         if (result.getExitCode() != 0 && !result.getStderr().contains("already exists")) {
-            throw new RuntimeException("Failed to create Gitea admin user: " + result.getStderr()
-                    + " / stdout: " + result.getStdout());
+            throw new RuntimeException(
+                    "Failed to create Gitea admin user: " + result.getStderr() + " / stdout: " + result.getStdout());
         }
     }
 
     /**
-     * Creates the test organisation and a public repository via the Gitea REST API. The repo is
-     * auto-initialised with a README so it has a {@code main} branch ready for pushes. Must be
-     * called after {@link #createAdminUser()}.
+     * Creates the test organisation and a public repository via the Gitea REST API. The repo is auto-initialised with a
+     * README so it has a {@code main} branch ready for pushes. Must be called after {@link #createAdminUser()}.
      */
     void createTestRepo() throws IOException, InterruptedException {
         var client = HttpClient.newHttpClient();
-        String auth = Base64.getEncoder()
-                .encodeToString((ADMIN_USER + ":" + ADMIN_PASSWORD).getBytes());
+        String auth = Base64.getEncoder().encodeToString((ADMIN_USER + ":" + ADMIN_PASSWORD).getBytes());
         String base = getBaseUrl();
 
         // Create organisation (ignore 422 if it already exists)
-        apiPost(
-                client,
-                auth,
-                base + "/api/v1/orgs",
-                "{\"username\":\"" + TEST_ORG + "\",\"visibility\":\"public\"}");
+        apiPost(client, auth, base + "/api/v1/orgs", "{\"username\":\"" + TEST_ORG + "\",\"visibility\":\"public\"}");
 
         // Create repository under the org (auto_init gives an initial commit on main)
         var resp = apiPost(
                 client,
                 auth,
                 base + "/api/v1/orgs/" + TEST_ORG + "/repos",
-                "{\"name\":\"" + TEST_REPO
-                        + "\",\"private\":false,\"auto_init\":true,\"default_branch\":\"main\"}");
+                "{\"name\":\"" + TEST_REPO + "\",\"private\":false,\"auto_init\":true,\"default_branch\":\"main\"}");
         if (resp.statusCode() >= 400) {
-            throw new RuntimeException(
-                    "Failed to create test repo (" + resp.statusCode() + "): " + resp.body());
+            throw new RuntimeException("Failed to create test repo (" + resp.statusCode() + "): " + resp.body());
         }
     }
 
diff --git a/jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/JettyProxyFixture.java b/jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/JettyProxyFixture.java
@@ -21,12 +21,10 @@
 import org.finos.gitproxy.servlet.filter.*;
 
 /**
- * Starts and stops a real Jetty server wired up identically to {@code GitProxyJettyApplication}
- * but with a single {@link GenericProxyProvider} pointing at the test Gitea instance, listening on
- * an ephemeral port.
+ * Starts and stops a real Jetty server wired up identically to {@code GitProxyJettyApplication} but with a single
+ * {@link GenericProxyProvider} pointing at the test Gitea instance, listening on an ephemeral port.
  *
- * <p>Intended for use inside {@code @Tag("e2e")} tests as a JUnit {@code @BeforeAll} / {@code
- * @AfterAll} resource.
+ * <p>Intended for use inside {@code @Tag("e2e")} tests as a JUnit {@code @BeforeAll} / {@code @AfterAll} resource.
  */
 class JettyProxyFixture implements AutoCloseable {
 
@@ -43,8 +41,7 @@ class JettyProxyFixture implements AutoCloseable {
         server.addConnector(connector);
 
         var pushStore = PushStoreFactory.inMemory();
-        var storeForwardCache =
-                new LocalRepositoryCache(Files.createTempDirectory("jgit-proxy-e2e-sf-"), 0, true);
+        var storeForwardCache = new LocalRepositoryCache(Files.createTempDirectory("jgit-proxy-e2e-sf-"), 0, true);
         var proxyCache = new LocalRepositoryCache();
 
         var provider = GenericProxyProvider.builder()
@@ -61,8 +58,7 @@ class JettyProxyFixture implements AutoCloseable {
         var resolver = new StoreAndForwardRepositoryResolver(storeForwardCache, provider);
         var gitServlet = new GitServlet();
         gitServlet.setRepositoryResolver(resolver);
-        gitServlet.setReceivePackFactory(
-                new StoreAndForwardReceivePackFactory(provider, commitConfig, pushStore));
+        gitServlet.setReceivePackFactory(new StoreAndForwardReceivePackFactory(provider, commitConfig, pushStore));
         gitServlet.setUploadPackFactory(new StoreAndForwardUploadPackFactory());
 
         String pushServletPath = PUSH_PREFIX + provider.servletPath();
@@ -71,13 +67,9 @@ class JettyProxyFixture implements AutoCloseable {
         gitHolder.setName("git-gitea-e2e");
         context.addServlet(gitHolder, pushMapping);
         context.addFilter(
-                new FilterHolder(new SmartHttpErrorFilter()),
-                pushMapping,
-                EnumSet.of(DispatcherType.REQUEST));
+                new FilterHolder(new SmartHttpErrorFilter()), pushMapping, EnumSet.of(DispatcherType.REQUEST));
         context.addFilter(
-                new FilterHolder(new BasicAuthChallengeFilter()),
-                pushMapping,
-                EnumSet.of(DispatcherType.REQUEST));
+                new FilterHolder(new BasicAuthChallengeFilter()), pushMapping, EnumSet.of(DispatcherType.REQUEST));
 
         // Transparent proxy GitProxyServlet on /proxy/...
         String proxyServletPath = PROXY_PREFIX + provider.servletPath();
@@ -96,10 +88,7 @@ class JettyProxyFixture implements AutoCloseable {
         addFilter(context, proxyMapping, new PushStoreAuditFilter(pushStore));
         addFilter(context, proxyMapping, new ForceGitClientFilter());
         addFilter(context, proxyMapping, new ParseGitRequestFilter(provider, PROXY_PREFIX));
-        addFilter(
-                context,
-                proxyMapping,
-                new EnrichPushCommitsFilter(provider, proxyCache, PROXY_PREFIX));
+        addFilter(context, proxyMapping, new EnrichPushCommitsFilter(provider, proxyCache, PROXY_PREFIX));
         addFilter(context, proxyMapping, new CheckAuthorEmailsFilter(commitConfig));
         addFilter(context, proxyMapping, new CheckCommitMessagesFilter(commitConfig));
         addFilter(context, proxyMapping, new GpgSignatureFilter(GpgConfig.defaultConfig()));
@@ -163,8 +152,7 @@ static CommitConfig buildCommitConfig() {
                 .message(CommitConfig.MessageConfig.builder()
                         .block(CommitConfig.BlockConfig.builder()
                                 .literals(List.of("WIP", "DO NOT MERGE", "fixup!", "squash!"))
-                                .patterns(List.of(
-                                        Pattern.compile("(?i)(password|secret|token)\\s*[=:]\\s*\\S+")))
+                                .patterns(List.of(Pattern.compile("(?i)(password|secret|token)\\s*[=:]\\s*\\S+")))
                                 .build())
                         .build())
                 .build();
diff --git a/jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/ProxyModeE2ETest.java b/jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/ProxyModeE2ETest.java
@@ -12,12 +12,11 @@
 /**
  * End-to-end tests for the <em>transparent proxy</em> path ({@code /proxy/...}).
  *
- * <p>Mirrors {@code test-proxy-pass.sh} and {@code test-proxy-fail.sh}: every test performs a real
- * {@code git clone} + commit + push through a live Jetty proxy that forwards to a containerised
- * Gitea instance.
+ * <p>Mirrors {@code test-proxy-pass.sh} and {@code test-proxy-fail.sh}: every test performs a real {@code git clone} +
+ * commit + push through a live Jetty proxy that forwards to a containerised Gitea instance.
  *
- * <p>Infrastructure is started once per class (containers are expensive) and each test clones into
- * its own temp directory so there are no ordering dependencies.
+ * <p>Infrastructure is started once per class (containers are expensive) and each test clones into its own temp
+ * directory so there are no ordering dependencies.
  */
 @Tag("e2e")
 @TestMethodOrder(MethodOrderer.OrderAnnotation.class)
@@ -61,14 +60,12 @@ private GitHelper helper() {
     }
 
     /**
-     * Clones the test repo, sets the given author identity, appends a timestamped line to a test
-     * file, stages and commits with {@code message}, then attempts a push.
+     * Clones the test repo, sets the given author identity, appends a timestamped line to a test file, stages and
+     * commits with {@code message}, then attempts a push.
      *
      * @return {@code true} if the push succeeded
      */
-    private boolean cloneCommitPush(
-            String dirSuffix, String authorEmail, String commitMessage)
-            throws Exception {
+    private boolean cloneCommitPush(String dirSuffix, String authorEmail, String commitMessage) throws Exception {
         GitHelper git = helper();
         Path repo = git.clone(repoUrl(), dirSuffix);
         git.setAuthor(repo, GiteaContainer.VALID_AUTHOR_NAME, authorEmail);
@@ -112,21 +109,15 @@ void multipleCleanCommits_pass() throws Exception {
     @Order(10)
     void noreplyLocalPart_blocked() throws Exception {
         assertFalse(
-                cloneCommitPush(
-                        "proxy-fail-noreply",
-                        "noreply@example.com",
-                        "feat: this commit has a noreply author"),
+                cloneCommitPush("proxy-fail-noreply", "noreply@example.com", "feat: this commit has a noreply author"),
                 "push with noreply@ address should be rejected");
     }
 
     @Test
     @Order(11)
     void noReplyHyphenLocalPart_blocked() throws Exception {
         assertFalse(
-                cloneCommitPush(
-                        "proxy-fail-noreply2",
-                        "no-reply@example.com",
-                        "feat: no-reply local part"),
+                cloneCommitPush("proxy-fail-noreply2", "no-reply@example.com", "feat: no-reply local part"),
                 "push with no-reply@ address should be rejected");
     }
 
@@ -157,9 +148,7 @@ void githubNoreplyEmail_blocked() throws Exception {
     void wipCommitMessage_blocked() throws Exception {
         assertFalse(
                 cloneCommitPush(
-                        "proxy-fail-wip",
-                        GiteaContainer.VALID_AUTHOR_EMAIL,
-                        "WIP: still working on this feature"),
+                        "proxy-fail-wip", GiteaContainer.VALID_AUTHOR_EMAIL, "WIP: still working on this feature"),
                 "push with WIP commit message should be rejected");
     }
 
@@ -179,9 +168,7 @@ void fixupCommitMessage_blocked() throws Exception {
     void doNotMergeCommitMessage_blocked() throws Exception {
         assertFalse(
                 cloneCommitPush(
-                        "proxy-fail-dnm",
-                        GiteaContainer.VALID_AUTHOR_EMAIL,
-                        "DO NOT MERGE - experimental branch"),
+                        "proxy-fail-dnm", GiteaContainer.VALID_AUTHOR_EMAIL, "DO NOT MERGE - experimental branch"),
                 "push with DO NOT MERGE message should be rejected");
     }
 
diff --git a/jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/StoreForwardModeE2ETest.java b/jgit-proxy-server/src/test/java/org/finos/gitproxy/e2e/StoreForwardModeE2ETest.java
