From decb4ea66e97dee3f3040bdfbe2a60fad205d756 Mon Sep 17 00:00:00 2001
From: Daniel Chao <dan.chao@apple.com>
Date: Thu, 17 Jul 2025 07:57:48 -0700
Subject: [PATCH] Improve message passing api docs (#1127)

1. Change `Binary` to `Bytes` (new type representing binary data)
2. Add documentation for `http.rewrites` option
---
 .../pages/message-passing-api.adoc            | 23 +++++++++----------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/docs/modules/bindings-specification/pages/message-passing-api.adoc b/docs/modules/bindings-specification/pages/message-passing-api.adoc
index 2d42efda..6b6674df 100644
--- a/docs/modules/bindings-specification/pages/message-passing-api.adoc
+++ b/docs/modules/bindings-specification/pages/message-passing-api.adoc
@@ -199,12 +199,17 @@ class Http {
   /// PEM format certificates to trust when making HTTP requests.
   ///
   /// If [null], Pkl will trust its own built-in certificates.
-  caCertificates: Binary?
+  caCertificates: Bytes? // <1>
 
   /// Configuration of the HTTP proxy to use.
   ///
   /// If [null], uses the operating system's proxy configuration.
   proxy: Proxy?
+
+  /// HTTP rewrites, from source prefix to target prefix.
+  ///
+  /// Each rewrite must start with `http://` or `https://`, and must end with `/`.
+  rewrites: Mapping<String, String>?
 }
 
 /// Settings that control how Pkl talks to HTTP proxies.
@@ -246,10 +251,8 @@ class Proxy {
   /// ```
   noProxy: Listing<String>(isDistinct)
 }
-
-typealias Binary = Any // <1>
 ----
-<1> link:{uri-messagepack-bin}[bin format] (not expressable in Pkl)
+<1> link:{uri-messagepack-bin}[bin format]
 
 Example:
 [source,json5]
@@ -347,14 +350,12 @@ requestId: Int
 evaluatorId: Int
 
 /// The evaluation contents, if successful.
-result: Binary? // <1>
+result: Bytes? // <1>
 
 /// A message detailing why evaluation failed.
 error: String?
-
-typealias Binary = Any // <1>
 ----
-<1> xref:binary-encoding.adoc[Pkl Binary Encoding] in link:{uri-messagepack-bin}[bin format] (not expressable in Pkl)
+<1> xref:binary-encoding.adoc[Pkl Binary Encoding] in link:{uri-messagepack-bin}[bin format]
 
 [[log]]
 === Log
@@ -425,14 +426,12 @@ requestId: Int
 evaluatorId: Int
 
 /// The contents of the resource.
-contents: Binary? // <1>
+contents: Bytes? // <1>
 
 /// The description of the error that occurred when reading this resource.
 error: String?
-
-typealias Binary = Any // <1>
 ----
-<1> MessagePack's link:https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family[bin format family] (not expressable in Pkl)
+<1> MessagePack's link:https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family[bin format family]
 
 [[read-module-request]]
 === Read Module Request