v2.2.0 foundation: queue hotfix + Fault + SingleFlight + CacheWriter

.github/workflows/perf-baseline.yml

@@ -0,0 +1,67 @@
+name: Perf Baseline
+
+on:
+  pull_request:
+    branches: [master, 2.2.0]
+
+jobs:
+  perf-baseline:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: maven
+
+      - name: Build (skip tests)
+        run: mvn -T8 install -DskipTests -q
+
+      - name: Install wrk
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq wrk
+
+      - name: Start Pantera
+        run: |
+          java -jar pantera-main/target/pantera-main-*.jar &
+          echo $! > /tmp/pantera.pid
+          # Wait for health endpoint
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:8080/api/health > /dev/null 2>&1; then
+              echo "Pantera started"
+              break
+            fi
+            sleep 2
+          done
+
+      - name: Run perf benchmark
+        run: |
+          chmod +x scripts/perf-benchmark.sh
+          scripts/perf-benchmark.sh http://localhost:8080 /tmp/measured.json
+
+      - name: Compare against baseline
+        run: |
+          chmod +x scripts/perf-compare.sh
+          scripts/perf-compare.sh tests/perf-baselines/npm-proxy.json /tmp/measured.json
+
+      - name: Stop Pantera
+        if: always()
+        run: |
+          if [ -f /tmp/pantera.pid ]; then
+            kill "$(cat /tmp/pantera.pid)" 2>/dev/null || true
+          fi
+
+      - name: Upload benchmark results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: perf-results
+          path: /tmp/measured.json
+          retention-days: 30

.gitignore

@@ -53,3 +53,10 @@ pantera-main/docker-compose/pantera/artifacts/php/composer.lock
 /benchmark/setup/repos-old/.tmp
 /pantera-backfill
 pantera-main/docker-compose/pantera/keys/
+logs/.analysis/
+performance/*/*
+!performance/results/.gitkeep
+performance/wiremock/__files/*.bin
+performance/pantera-config.yml
+performance/secrets/*.pem
+performance/fixtures/uploads/*.tgz

build-tools/pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.auto1.pantera</groupId>
     <artifactId>build-tools</artifactId>
-    <version>2.1.3</version>
+    <version>2.2.0</version>
 
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

composer-adapter/pom.xml

@@ -27,10 +27,10 @@ SOFTWARE.
   <parent>
     <groupId>com.auto1.pantera</groupId>
     <artifactId>pantera</artifactId>
-    <version>2.1.3</version>
+    <version>2.2.0</version>
   </parent>
   <artifactId>composer-adapter</artifactId>
-  <version>2.1.3</version>
+  <version>2.2.0</version>
   <packaging>jar</packaging>
   <name>composer-files</name>
   <description>Turns your files/objects into PHP Composer artifacts</description>
@@ -45,19 +45,19 @@ SOFTWARE.
     <dependency>
       <groupId>com.auto1.pantera</groupId>
       <artifactId>http-client</artifactId>
-      <version>2.1.3</version>
+      <version>2.2.0</version>
       <scope>compile</scope>
     </dependency>
     <dependency>
       <groupId>com.auto1.pantera</groupId>
       <artifactId>files-adapter</artifactId>
-      <version>2.1.3</version>
+      <version>2.2.0</version>
       <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>com.auto1.pantera</groupId>
       <artifactId>pantera-storage-core</artifactId>
-      <version>2.1.3</version>
+      <version>2.2.0</version>
       <scope>compile</scope>
       <!-- Do not remove this exclusion! No tests will run if dependency is not excluded! -->
       <exclusions>
@@ -76,7 +76,7 @@ SOFTWARE.
     <dependency>
       <groupId>com.auto1.pantera</groupId>
       <artifactId>vertx-server</artifactId>
-      <version>2.1.3</version>
+      <version>2.2.0</version>
       <scope>test</scope>
     </dependency>
   </dependencies>

composer-adapter/src/main/java/com/auto1/pantera/composer/cooldown/ComposerCooldownResponseFactory.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2025-2026 Auto1 Group
+ * Maintainers: Auto1 DevOps Team
+ * Lead Maintainer: Ayd Asraf
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License v3.0.
+ *
+ * Originally based on Artipie (https://github.com/artipie/artipie), MIT License.
+ */
+package com.auto1.pantera.composer.cooldown;
+
+import com.auto1.pantera.cooldown.api.CooldownBlock;
+import com.auto1.pantera.cooldown.response.CooldownResponseFactory;
+import com.auto1.pantera.http.Response;
+import com.auto1.pantera.http.ResponseBuilder;
+
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+
+/**
+ * Composer-specific cooldown 403 response factory.
+ *
+ * <p>Returns {@code application/json} body matching the Composer error format.</p>
+ *
+ * @since 2.2.0
+ */
+public final class ComposerCooldownResponseFactory implements CooldownResponseFactory {
+
+    private static final DateTimeFormatter ISO = DateTimeFormatter.ISO_OFFSET_DATE_TIME;
+
+    @Override
+    public Response forbidden(final CooldownBlock block) {
+        final String until = ISO.format(
+            block.blockedUntil().atOffset(ZoneOffset.UTC)
+        );
+        final long retryAfter = Math.max(
+            1L,
+            Duration.between(Instant.now(), block.blockedUntil()).getSeconds()
+        );
+        final String body = String.format(
+            "{\"error\":\"version in cooldown\",\"blocked_until\":\"%s\"}", until
+        );
+        return ResponseBuilder.forbidden()
+            .header("Retry-After", String.valueOf(retryAfter))
+            .header("X-Pantera-Cooldown", "blocked")
+            .jsonBody(body)
+            .build();
+    }
+
+    @Override
+    public String repoType() {
+        return "composer";
+    }
+}

composer-adapter/src/main/java/com/auto1/pantera/composer/cooldown/ComposerMetadataFilter.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2025-2026 Auto1 Group
+ * Maintainers: Auto1 DevOps Team
+ * Lead Maintainer: Ayd Asraf
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License v3.0.
+ *
+ * Originally based on Artipie (https://github.com/artipie/artipie), MIT License.
+ */
+package com.auto1.pantera.composer.cooldown;
+
+import com.auto1.pantera.cooldown.metadata.MetadataFilter;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+
+import java.util.Set;
+
+/**
+ * PHP Composer metadata filter implementing cooldown SPI.
+ * Removes blocked version keys from the Composer packages.json version map.
+ *
+ * <p>Filters the {@code packages.{vendor/package}} object by removing blocked
+ * version keys. Composer has no "latest" tag in the metadata format, so
+ * {@link #updateLatest(JsonNode, String)} is a no-op that returns metadata unchanged.</p>
+ *
+ * @since 2.2.0
+ */
+public final class ComposerMetadataFilter implements MetadataFilter<JsonNode> {
+
+    @Override
+    public JsonNode filter(final JsonNode metadata, final Set<String> blockedVersions) {
+        if (blockedVersions.isEmpty()) {
+            return metadata;
+        }
+        if (!(metadata instanceof ObjectNode)) {
+            return metadata;
+        }
+        final JsonNode packages = metadata.get("packages");
+        if (packages == null || !packages.isObject() || packages.size() == 0) {
+            return metadata;
+        }
+        final String name = packages.fieldNames().next();
+        final JsonNode pkgNode = packages.get(name);
+        if (pkgNode != null && pkgNode.isObject()) {
+            final ObjectNode versionsObj = (ObjectNode) pkgNode;
+            for (final String blocked : blockedVersions) {
+                versionsObj.remove(blocked);
+            }
+        }
+        return metadata;
+    }
+
+    @Override
+    public JsonNode updateLatest(final JsonNode metadata, final String newLatest) {
+        // Composer packages.json has no "latest" tag — the client resolves
+        // version constraints from the full version map. No-op.
+        return metadata;
+    }
+}

composer-adapter/src/main/java/com/auto1/pantera/composer/cooldown/ComposerMetadataParser.java

@@ -0,0 +1,135 @@
+/*
+ * Copyright (c) 2025-2026 Auto1 Group
+ * Maintainers: Auto1 DevOps Team
+ * Lead Maintainer: Ayd Asraf
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License v3.0.
+ *
+ * Originally based on Artipie (https://github.com/artipie/artipie), MIT License.
+ */
+package com.auto1.pantera.composer.cooldown;
+
+import com.auto1.pantera.cooldown.metadata.MetadataParseException;
+import com.auto1.pantera.cooldown.metadata.MetadataParser;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * PHP Composer metadata parser implementing cooldown SPI.
+ * Parses Composer packages.json metadata and extracts version information.
+ *
+ * <p>Composer metadata structure (packages endpoint {@code /packages/{vendor}/{pkg}.json}
+ * or {@code /p2/{vendor}/{pkg}.json}):</p>
+ * <pre>
+ * {
+ *   "packages": {
+ *     "vendor/package": {
+ *       "1.0.0": {"name": "vendor/package", "version": "1.0.0", ...},
+ *       "1.1.0": {"name": "vendor/package", "version": "1.1.0", ...},
+ *       "2.0.0": {"name": "vendor/package", "version": "2.0.0", ...}
+ *     }
+ *   }
+ * }
+ * </pre>
+ *
+ * @since 2.2.0
+ */
+public final class ComposerMetadataParser implements MetadataParser<JsonNode> {
+
+    /**
+     * Shared ObjectMapper for JSON parsing (thread-safe).
+     */
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    /**
+     * Content type for Composer metadata.
+     */
+    private static final String CONTENT_TYPE = "application/json";
+
+    @Override
+    public JsonNode parse(final byte[] bytes) throws MetadataParseException {
+        if (bytes == null || bytes.length == 0) {
+            throw new MetadataParseException("Empty or null Composer metadata");
+        }
+        try {
+            final JsonNode node = MAPPER.readTree(bytes);
+            if (node == null) {
+                throw new MetadataParseException("Parsed Composer metadata is null");
+            }
+            return node;
+        } catch (final IOException ex) {
+            throw new MetadataParseException("Failed to parse Composer metadata JSON", ex);
+        }
+    }
+
+    @Override
+    public List<String> extractVersions(final JsonNode metadata) {
+        final JsonNode pkgNode = this.findPackageNode(metadata);
+        if (pkgNode == null || !pkgNode.isObject()) {
+            return Collections.emptyList();
+        }
+        final List<String> result = new ArrayList<>();
+        final Iterator<String> fields = pkgNode.fieldNames();
+        while (fields.hasNext()) {
+            result.add(fields.next());
+        }
+        return result;
+    }
+
+    @Override
+    public Optional<String> getLatestVersion(final JsonNode metadata) {
+        // Composer packages.json does not have a "latest" tag;
+        // the client resolves constraints from the full version map.
+        return Optional.empty();
+    }
+
+    @Override
+    public String contentType() {
+        return CONTENT_TYPE;
+    }
+
+    /**
+     * Get the package name from metadata.
+     * Returns the first (and typically only) key under the "packages" object.
+     *
+     * @param metadata Parsed metadata
+     * @return Package name if present, empty otherwise
+     */
+    public Optional<String> getPackageName(final JsonNode metadata) {
+        final JsonNode packages = metadata.get("packages");
+        if (packages != null && packages.isObject() && packages.size() > 0) {
+            return Optional.of(packages.fieldNames().next());
+        }
+        return Optional.empty();
+    }
+
+    /**
+     * Find the package version-map node inside the metadata.
+     * Navigates {@code packages.{first-key}} to reach the object whose
+     * field names are version strings.
+     *
+     * @param metadata Root metadata node
+     * @return Package version map node, or {@code null} if not found
+     */
+    private JsonNode findPackageNode(final JsonNode metadata) {
+        final JsonNode packages = metadata.get("packages");
+        if (packages == null || !packages.isObject() || packages.size() == 0) {
+            return null;
+        }
+        final String name = packages.fieldNames().next();
+        final JsonNode pkgNode = packages.get(name);
+        if (pkgNode != null && pkgNode.isObject()) {
+            return pkgNode;
+        }
+        return null;
+    }
+}