Add support for customizing HTTP headers (#1196)

This PR adds support for custom HTTP headers, introducing a `--http-header` CLI flag to accept `key=value` pairs. These headers can also be specified within the `setting.pkl` file. Closes #633 SPICE: https://github.com/apple/pkl-evolution/pull/24 --------- Co-authored-by: Jen Basch <jbasch94@gmail.com> Co-authored-by: Islon Scherer <islonscherer@gmail.com>
2026-05-25 16:19:20 +02:00 · 2026-05-13 05:53:59 +09:00
parent fe58405220
commit 14085c18bb
14 changed files with 358 additions and 18 deletions
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@ package org.pkl.core.evaluatorSettings;
 import java.net.URI;
 import java.net.URISyntaxException;
 import java.nio.file.Path;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
@@ -27,13 +28,17 @@ import java.util.Objects;
 import java.util.function.BiFunction;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
+import java.util.stream.Stream;
 import org.pkl.core.Duration;
 import org.pkl.core.PNull;
 import org.pkl.core.PObject;
+import org.pkl.core.Pair;
 import org.pkl.core.PklBugException;
 import org.pkl.core.PklException;
 import org.pkl.core.Value;
 import org.pkl.core.util.ErrorMessages;
+import org.pkl.core.util.GlobResolver;
+import org.pkl.core.util.GlobResolver.InvalidGlobPatternException;
 import org.pkl.core.util.Nullable;

 /** Java version of {@code pkl.EvaluatorSettings}. */
@@ -126,8 +131,11 @@ public record PklEvaluatorSettings(
        traceMode == null ? null : TraceMode.valueOf(traceMode.toUpperCase()));
  }

-  public record Http(@Nullable Proxy proxy, @Nullable Map<URI, URI> rewrites) {
-    public static final Http DEFAULT = new Http(null, Collections.emptyMap());
+  public record Http(
+      @Nullable Proxy proxy,
+      @Nullable Map<URI, URI> rewrites,
+      @Nullable List<Pair<Pattern, List<Pair<String, String>>>> headers) {
+    public static final Http DEFAULT = new Http(null, Collections.emptyMap(), null);

    @SuppressWarnings("unchecked")
    public static @Nullable Http parse(@Nullable Value input) {
@@ -136,10 +144,9 @@ public record PklEvaluatorSettings(
      } else if (input instanceof PObject http) {
        var proxy = Proxy.parse((Value) http.getProperty("proxy"));
        var rewrites = http.getProperty("rewrites");
-        if (rewrites instanceof PNull) {
-          return new Http(proxy, null);
-        } else {
-          var parsedRewrites = new HashMap<URI, URI>();
+        HashMap<URI, URI> parsedRewrites = null;
+        if (!(rewrites instanceof PNull)) {
+          parsedRewrites = new HashMap<>();
          for (var entry : ((Map<String, String>) rewrites).entrySet()) {
            var key = entry.getKey();
            var value = entry.getValue();
@@ -149,8 +156,37 @@ public record PklEvaluatorSettings(
              throw new PklException(ErrorMessages.create("invalidUri", e.getInput()));
            }
          }
-          return new Http(proxy, parsedRewrites);
        }
+        var headerDefs = http.getProperty("headers");
+        List<Pair<Pattern, List<Pair<String, String>>>> parsedHeaderDefs = null;
+        if (!(headerDefs instanceof PNull)) {
+          parsedHeaderDefs = new ArrayList<>();
+          var headerDefsMap = (Map<String, Map<String, Object>>) headerDefs;
+          for (var entry : headerDefsMap.entrySet()) {
+            var stringPattern = entry.getKey();
+            var headersMap = entry.getValue();
+            try {
+              var urlPattern = GlobResolver.toRegexPattern(stringPattern);
+              var pairs =
+                  headersMap.entrySet().stream()
+                      .flatMap(
+                          header -> {
+                            var value = header.getValue();
+                            if (value instanceof List) {
+                              return ((List<String>) value)
+                                  .stream().map(v -> new Pair(header.getKey(), v));
+                            } else {
+                              return Stream.of(new Pair(header.getKey(), value));
+                            }
+                          })
+                      .toList();
+              parsedHeaderDefs.add(new Pair(urlPattern, pairs));
+            } catch (InvalidGlobPatternException e) {
+              throw new PklException(ErrorMessages.create("invalidUri", stringPattern));
+            }
+          }
+        }
+        return new Http(proxy, parsedRewrites, parsedHeaderDefs);
      } else {
        throw PklBugException.unreachableCode();
      }
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -23,7 +23,9 @@ import java.net.http.HttpTimeoutException;
 import java.nio.file.Path;
 import java.util.List;
 import java.util.Map;
+import java.util.regex.Pattern;
 import javax.net.ssl.SSLContext;
+import org.pkl.core.Pair;
 import org.pkl.core.util.Nullable;

 /**
@@ -150,6 +152,14 @@ public interface HttpClient extends AutoCloseable {
     */
    Builder addRewrite(URI sourcePrefix, URI targetPrefix);

+    /**
+     * Sets the HTTP headers for the request, replacing any previously configured headers.
+     *
+     * <p>This method clears all existing headers and replaces them with the contents of the
+     * provided map.
+     */
+    Builder setHeaders(List<Pair<Pattern, List<Pair<String, String>>>> headers);
+
    /**
     * Creates a new {@code HttpClient} from the current state of this builder.
     *
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -27,6 +27,8 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.function.Supplier;
+import java.util.regex.Pattern;
+import org.pkl.core.Pair;
 import org.pkl.core.Release;
 import org.pkl.core.http.HttpClient.Builder;

@@ -39,6 +41,7 @@ final class HttpClientBuilder implements HttpClient.Builder {
  private int testPort = -1;
  private ProxySelector proxySelector;
  private Map<URI, URI> rewrites = new HashMap<>();
+  private List<Pair<Pattern, List<Pair<String, String>>>> headers = new ArrayList<>();

  HttpClientBuilder() {
    var release = Release.current();
@@ -110,6 +113,12 @@ final class HttpClientBuilder implements HttpClient.Builder {
    return this;
  }

+  @Override
+  public Builder setHeaders(List<Pair<Pattern, List<Pair<String, String>>>> headers) {
+    this.headers = headers;
+    return this;
+  }
+
  @Override
  public HttpClient build() {
    return doBuild().get();
@@ -128,7 +137,8 @@ final class HttpClientBuilder implements HttpClient.Builder {
    return () -> {
      var jdkClient =
          new JdkHttpClient(certificateFiles, certificateBytes, connectTimeout, proxySelector);
-      return new RequestRewritingClient(userAgent, requestTimeout, testPort, jdkClient, rewrites);
+      return new RequestRewritingClient(
+          userAgent, requestTimeout, testPort, jdkClient, rewrites, headers);
    };
  }
 }
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -28,7 +28,10 @@ import java.util.Map;
 import java.util.Map.Entry;
 import java.util.Objects;
 import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.regex.Pattern;
+import java.util.stream.Stream;
 import javax.annotation.concurrent.ThreadSafe;
+import org.pkl.core.Pair;
 import org.pkl.core.PklBugException;
 import org.pkl.core.util.HttpUtils;
 import org.pkl.core.util.Nullable;
@@ -54,6 +57,7 @@ final class RequestRewritingClient implements HttpClient {
  final int testPort;
  final HttpClient delegate;
  private final List<Entry<URI, URI>> rewrites;
+  private final List<Pair<Pattern, List<Pair<String, String>>>> headers;

  private final AtomicBoolean closed = new AtomicBoolean();

@@ -62,7 +66,8 @@ final class RequestRewritingClient implements HttpClient {
      Duration requestTimeout,
      int testPort,
      HttpClient delegate,
-      Map<URI, URI> rewrites) {
+      Map<URI, URI> rewrites,
+      List<Pair<Pattern, List<Pair<String, String>>>> headers) {
    this.userAgent = userAgent;
    this.requestTimeout = requestTimeout;
    this.testPort = testPort;
@@ -72,6 +77,7 @@ final class RequestRewritingClient implements HttpClient {
            .map((it) -> Map.entry(normalizeRewrite(it.getKey()), normalizeRewrite(it.getValue())))
            .sorted(Comparator.comparingInt((it) -> -it.getKey().toString().length()))
            .toList();
+    this.headers = headers;
  }

  @Override
@@ -112,6 +118,9 @@ final class RequestRewritingClient implements HttpClient {
        .map()
        .forEach((name, values) -> values.forEach(value -> builder.header(name, value)));
    builder.setHeader("User-Agent", userAgent);
+    for (var header : this.getHeaders(original.uri())) {
+      builder.header(header.getFirst(), header.getSecond());
+    }

    var method = original.method();
    original
@@ -216,6 +225,16 @@ final class RequestRewritingClient implements HttpClient {
    return ret;
  }

+  private List<Pair<String, String>> getHeaders(URI uri) {
+    return headers.stream()
+        .flatMap(
+            rule ->
+                rule.getFirst().asPredicate().test(uri.toString())
+                    ? rule.getSecond().stream()
+                    : Stream.empty())
+        .toList();
+  }
+
  private void checkNotClosed(HttpRequest request) {
    if (closed.get()) {
      throw new IllegalStateException(
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -52,6 +52,34 @@ public final class IoUtils {

  private static final Pattern windowsPathLike = Pattern.compile("\\w:\\\\.*");

+  private static final Pattern headerNameLike = Pattern.compile("^[a-zA-Z0-9!#$%&'*+-.^_`|~]+$");
+
+  private static final Pattern headerValueLike =
+      Pattern.compile("^[\\t\\u0020-\\u007E\\u0080-\\u00FF]*$");
+
+  private static final String[] reservedHeaderNames = {
+    "accept-charset",
+    "accept-encoding",
+    "connection",
+    "content-length",
+    "cookie",
+    "date",
+    "dnt",
+    "expect",
+    "host",
+    "keep-alive",
+    "origin",
+    "permissions-policy",
+    "referer",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "via"
+  };
+
+  private static final String[] reservedHeaderPrefixes = {"proxy-", "sec-", "access-control-"};
+
  private IoUtils() {}

  public static URL toUrl(URI uri) throws IOException {
@@ -546,7 +574,7 @@ public final class IoUtils {
    }

    // don't use ServiceLoader.load(Class)
-    // because loading services from thread context class loader doesn't work inside gradle plugins
+    // because loading services from thread context class loader doesn't work inside Gradle plugins
    return ServiceLoader.load(serviceClass, IoUtils.class.getClassLoader());
  }

@@ -854,4 +882,38 @@ public final class IoUtils {
          "Rewrite rule must end with '/', but was '%s'".formatted(rewrite));
    }
  }
+
+  private static boolean isReservedHeaderName(String headerName) {
+    return Arrays.stream(reservedHeaderNames).anyMatch((reserved) -> headerName.equals(reserved));
+  }
+
+  private static boolean hasReservedHeaderPrefix(String headerName) {
+    return Arrays.stream(reservedHeaderPrefixes)
+        .anyMatch((prefix) -> headerName.startsWith(prefix));
+  }
+
+  public static void validateHeaderName(String headerName) {
+
+    if (isReservedHeaderName(headerName)) {
+      throw new IllegalArgumentException(
+          "HTTP header '%s' is a reserved header".formatted(headerName));
+    }
+
+    if (hasReservedHeaderPrefix(headerName)) {
+      throw new IllegalArgumentException(
+          "HTTP header '%s' starts with a reserved header prefix".formatted(headerName));
+    }
+
+    if (!headerNameLike.matcher(headerName).matches()) {
+      throw new IllegalArgumentException(
+          "HTTP header name '%s' has an invalid syntax".formatted(headerName));
+    }
+  }
+
+  public static void validateHeaderValue(String headerValue) {
+    if (!headerValueLike.matcher(headerValue).matches()) {
+      throw new IllegalArgumentException(
+          "HTTP header value '%s' has an invalid syntax".formatted(headerValue));
+    }
+  }
 }
@@ -1124,3 +1124,9 @@ Option {1}s must not overlap with built-in options.
 commandFlagInvalidType=\
 Option `{0}` with annotation `@{1}` has invalid type `{2}`.\n\
 Expected type: `{3}`
+
+invalidHeaderName=\
+HTTP header name `{0}` has invalid syntax.
+
+invalidHeaderValue=\
+HTTP header value `{0}` has invalid syntax.