From 82ff1545919e64b1bac4b96fa29f6acb49d54ed5 Mon Sep 17 00:00:00 2001 From: Bailey Hayes Date: Thu, 26 Feb 2026 13:56:22 -0500 Subject: [PATCH 1/3] feat(http): size-exceeded error variant Opting for documenting two floors, one for individual fields and the other for aggregate. Exceeding either will fail with `header-error.size-exceeded`. Resolves #889 --- proposals/cli/wit-0.3.0-draft/deps.lock | 8 ++++---- proposals/http/wit-0.3.0-draft/deps.lock | 8 ++++---- proposals/http/wit-0.3.0-draft/types.wit | 26 +++++++++++++++++++++++- 3 files changed, 33 insertions(+), 9 deletions(-) diff --git a/proposals/cli/wit-0.3.0-draft/deps.lock b/proposals/cli/wit-0.3.0-draft/deps.lock index 7d4bde4e..82035af8 100644 --- a/proposals/cli/wit-0.3.0-draft/deps.lock +++ b/proposals/cli/wit-0.3.0-draft/deps.lock @@ -5,8 +5,8 @@ sha512 = "f08a2828b88fc6ddea935af584531c484ad4a7a5f30340265e11e91b2bfe0f81e74a66 [filesystem] path = "../../filesystem/wit-0.3.0-draft" -sha256 = "184861e98785957311bfaab242cdf9e66a9ecca11fe2c493b840c461b2361088" -sha512 = "50fa8801fc0a2c1ecfa3cea52af57836f98a12bb0a264439c13bbdcc0e269b3b37ade38b903d6ce10594d1f585d02ef993f3f769c4cddeebdfc00bf93734ed25" +sha256 = "8808ea3adfbc1a025d649b82ddf4f38232ca4377100cfe671d80d5ee37fa3147" +sha512 = "19f4eb8fa62e96ba37b3ea231af6a3bc396c28f82935018a3322441321936b34fb0e44360b378145fcb681d9fea810745969d8baab02ae6017be1784be8abe45" [random] path = "../../random/wit-0.3.0-draft" @@ -15,5 +15,5 @@ sha512 = "812ce57aa13ff3128779d41f4dad50714365e4f9cfd2e1b13458a885fa65da05e409f1 [sockets] path = "../../sockets/wit-0.3.0-draft" -sha256 = "985821e86f2643d90b7a100420a44a5a60a6838adcf76fdb90a66255e3926dde" -sha512 = "9ba1e9456c0dc02800ba738acd382a4113103bed72127396546c5f0ad3d38dd5c8e077443bd508b15f86f6095706907e9cb258cccab37c273b4c597a238987e7" +sha256 = "0be70fab90ec1d62e620f37f8fc55397222ceb68ca8387eb0503df7173782634" +sha512 = "997e336258dd3d8d1bf1b27463e77d1dc2160eb13fff899c93b446973f5efbc59448a23279b60568679c08e006a20cc88769ec74d6d30baa4e7a17df0bdb2c30" diff --git a/proposals/http/wit-0.3.0-draft/deps.lock b/proposals/http/wit-0.3.0-draft/deps.lock index e8f05aec..2354b136 100644 --- a/proposals/http/wit-0.3.0-draft/deps.lock +++ b/proposals/http/wit-0.3.0-draft/deps.lock @@ -10,13 +10,13 @@ sha256 = "888647625fec3eaaf276cb884e426bc32bfa79ced22955f10eb239df74c8550c" sha512 = "f08a2828b88fc6ddea935af584531c484ad4a7a5f30340265e11e91b2bfe0f81e74a660a512f72e5197d60278feccc00534833ebd73868e801859dd31a61bdbb" [filesystem] -sha256 = "184861e98785957311bfaab242cdf9e66a9ecca11fe2c493b840c461b2361088" -sha512 = "50fa8801fc0a2c1ecfa3cea52af57836f98a12bb0a264439c13bbdcc0e269b3b37ade38b903d6ce10594d1f585d02ef993f3f769c4cddeebdfc00bf93734ed25" +sha256 = "8808ea3adfbc1a025d649b82ddf4f38232ca4377100cfe671d80d5ee37fa3147" +sha512 = "19f4eb8fa62e96ba37b3ea231af6a3bc396c28f82935018a3322441321936b34fb0e44360b378145fcb681d9fea810745969d8baab02ae6017be1784be8abe45" [random] sha256 = "5794796c909d6656fcbae6bed28265210ca57308a624119ac0a472326a75aa8f" sha512 = "812ce57aa13ff3128779d41f4dad50714365e4f9cfd2e1b13458a885fa65da05e409f145deefa25c4a82e0e301a41e2e6572705b35752dc33908d565a73a2e9c" [sockets] -sha256 = "985821e86f2643d90b7a100420a44a5a60a6838adcf76fdb90a66255e3926dde" -sha512 = "9ba1e9456c0dc02800ba738acd382a4113103bed72127396546c5f0ad3d38dd5c8e077443bd508b15f86f6095706907e9cb258cccab37c273b4c597a238987e7" +sha256 = "0be70fab90ec1d62e620f37f8fc55397222ceb68ca8387eb0503df7173782634" +sha512 = "997e336258dd3d8d1bf1b27463e77d1dc2160eb13fff899c93b446973f5efbc59448a23279b60568679c08e006a20cc88769ec74d6d30baa4e7a17df0bdb2c30" diff --git a/proposals/http/wit-0.3.0-draft/types.wit b/proposals/http/wit-0.3.0-draft/types.wit index 22f907d9..521ba22d 100644 --- a/proposals/http/wit-0.3.0-draft/types.wit +++ b/proposals/http/wit-0.3.0-draft/types.wit @@ -116,6 +116,17 @@ interface types { /// This error indicates that the operation on the `fields` was not /// permitted because the fields are immutable. immutable, + + /// This error indicates that the operation would exceed an + /// implementation-defined limit on field sizes. This may apply to + /// an individual `field-value`, a single `field-name` plus all its + /// values, or the total aggregate size of all fields. + /// + /// Implementations MUST accept individual field values of at least + /// 8192 bytes and total aggregate field sections of at least 16384 + /// bytes. These minimums ensure portability across common HTTP + /// servers and match HTTP/2's minimum SETTINGS_MAX_FRAME_SIZE. + size-exceeded, } /// This type enumerates the different kinds of errors that may occur when @@ -158,6 +169,12 @@ interface types { /// original casing used to construct or mutate the `fields` resource. The `fields` /// resource should use that original casing when serializing the fields for /// transport or when returning them from a method. + /// + /// Implementations may impose limits on individual field values and on total + /// aggregate field section size. Operations that would exceed these limits + /// fail with `header-error.size-exceeded`. Implementations MUST accept + /// individual field values of at least 8192 bytes and total aggregate field + /// sections of at least 16384 bytes. @since(version = 0.3.0-rc-2026-02-09) resource fields { @@ -180,7 +197,8 @@ interface types { /// well-formed, so they are represented as a raw list of bytes. /// /// An error result will be returned if any header or value was - /// syntactically invalid, or if a header was forbidden. + /// syntactically invalid, if a header was forbidden, or if the + /// entries would exceed an implementation size limit. from-list: static func( entries: list> ) -> result; @@ -199,6 +217,9 @@ interface types { /// name, if they have been set. /// /// Fails with `header-error.immutable` if the `fields` are immutable. + /// + /// Fails with `header-error.size-exceeded` if the name or values would + /// exceed an implementation-defined size limit. set: func(name: field-name, value: list) -> result<_, header-error>; /// Delete all values for a name. Does nothing if no values for the name @@ -219,6 +240,9 @@ interface types { /// values for that name. /// /// Fails with `header-error.immutable` if the `fields` are immutable. + /// + /// Fails with `header-error.size-exceeded` if the value would exceed + /// an implementation-defined size limit. append: func(name: field-name, value: field-value) -> result<_, header-error>; /// Retrieve the full set of names and values in the Fields. Like the From a16e4718016028d5d3540dcd62565c84255a1c74 Mon Sep 17 00:00:00 2001 From: Bailey Hayes Date: Mon, 2 Mar 2026 17:36:20 -0500 Subject: [PATCH 2/3] feat(http): add other to variants Defensively extend the variants for http, related to #892 I used option to match error-code's internal-error(option) --- proposals/http/wit-0.3.0-draft/types.wit | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/proposals/http/wit-0.3.0-draft/types.wit b/proposals/http/wit-0.3.0-draft/types.wit index 521ba22d..e19c3a5e 100644 --- a/proposals/http/wit-0.3.0-draft/types.wit +++ b/proposals/http/wit-0.3.0-draft/types.wit @@ -127,6 +127,14 @@ interface types { /// bytes. These minimums ensure portability across common HTTP /// servers and match HTTP/2's minimum SETTINGS_MAX_FRAME_SIZE. size-exceeded, + + /// This is a catch-all error for anything that doesn't fit cleanly into a + /// more specific case. Implementations can use this to extend the error + /// type without breaking existing code. It also includes an optional + /// string for an unstructured description of the error. Users should not + /// depend on the string for diagnosing errors, as it's not required to be + /// consistent between implementations. + other(option), } /// This type enumerates the different kinds of errors that may occur when @@ -139,6 +147,14 @@ interface types { /// Indicates that the operation on the `request-options` was not permitted /// because it is immutable. immutable, + + /// This is a catch-all error for anything that doesn't fit cleanly into a + /// more specific case. Implementations can use this to extend the error + /// type without breaking existing code. It also includes an optional + /// string for an unstructured description of the error. Users should not + /// depend on the string for diagnosing errors, as it's not required to be + /// consistent between implementations. + other(option), } /// Field names are always strings. From 09c76e3d49e597398307d6e7806d89d3892feb39 Mon Sep 17 00:00:00 2001 From: Bailey Hayes Date: Tue, 3 Mar 2026 18:06:37 -0500 Subject: [PATCH 3/3] fix(http): remove implementation limit recommendations Specific minimum sizes are intentionally left unspecified. Implementations operate in diverse environments with varying constraints, so limits are implementation-defined. Making operations fallible with size-exceeded is sufficient to ensure correct error handling without prescribing specific thresholds. --- proposals/cli/wit-0.3.0-draft/deps.lock | 8 ++++---- proposals/http/wit-0.3.0-draft/deps.lock | 8 ++++---- proposals/http/wit-0.3.0-draft/types.wit | 9 +-------- 3 files changed, 9 insertions(+), 16 deletions(-) diff --git a/proposals/cli/wit-0.3.0-draft/deps.lock b/proposals/cli/wit-0.3.0-draft/deps.lock index 82035af8..c6708067 100644 --- a/proposals/cli/wit-0.3.0-draft/deps.lock +++ b/proposals/cli/wit-0.3.0-draft/deps.lock @@ -10,10 +10,10 @@ sha512 = "19f4eb8fa62e96ba37b3ea231af6a3bc396c28f82935018a3322441321936b34fb0e44 [random] path = "../../random/wit-0.3.0-draft" -sha256 = "5794796c909d6656fcbae6bed28265210ca57308a624119ac0a472326a75aa8f" -sha512 = "812ce57aa13ff3128779d41f4dad50714365e4f9cfd2e1b13458a885fa65da05e409f145deefa25c4a82e0e301a41e2e6572705b35752dc33908d565a73a2e9c" +sha256 = "2d54fe2815781a7462f3540b0959842b7e15d9fe8530c2b961b35451b6922670" +sha512 = "ac1a04d180f8aa11ac82529a0de7ff01c8d51d10424806aefe1c1d52ea9ade9911eaee2b3f7d9c23f4b3bfdff469af6482f4a9e5b800c465b9fb7b73ccc635c7" [sockets] path = "../../sockets/wit-0.3.0-draft" -sha256 = "0be70fab90ec1d62e620f37f8fc55397222ceb68ca8387eb0503df7173782634" -sha512 = "997e336258dd3d8d1bf1b27463e77d1dc2160eb13fff899c93b446973f5efbc59448a23279b60568679c08e006a20cc88769ec74d6d30baa4e7a17df0bdb2c30" +sha256 = "5e7010b31fc80b5484cdcad7bfaae9dbb2134d3debfa6a90c69c30ec8cf7d55e" +sha512 = "3863bd53d4ef1815f0f0f48d4032e3232322a3dbfa875eb573df2940264aacfe55d672886323406e5942ffc38ed5ad7dce91fcff3ff1e2e072773bb6dd9c7cd1" diff --git a/proposals/http/wit-0.3.0-draft/deps.lock b/proposals/http/wit-0.3.0-draft/deps.lock index 2354b136..11113573 100644 --- a/proposals/http/wit-0.3.0-draft/deps.lock +++ b/proposals/http/wit-0.3.0-draft/deps.lock @@ -14,9 +14,9 @@ sha256 = "8808ea3adfbc1a025d649b82ddf4f38232ca4377100cfe671d80d5ee37fa3147" sha512 = "19f4eb8fa62e96ba37b3ea231af6a3bc396c28f82935018a3322441321936b34fb0e44360b378145fcb681d9fea810745969d8baab02ae6017be1784be8abe45" [random] -sha256 = "5794796c909d6656fcbae6bed28265210ca57308a624119ac0a472326a75aa8f" -sha512 = "812ce57aa13ff3128779d41f4dad50714365e4f9cfd2e1b13458a885fa65da05e409f145deefa25c4a82e0e301a41e2e6572705b35752dc33908d565a73a2e9c" +sha256 = "2d54fe2815781a7462f3540b0959842b7e15d9fe8530c2b961b35451b6922670" +sha512 = "ac1a04d180f8aa11ac82529a0de7ff01c8d51d10424806aefe1c1d52ea9ade9911eaee2b3f7d9c23f4b3bfdff469af6482f4a9e5b800c465b9fb7b73ccc635c7" [sockets] -sha256 = "0be70fab90ec1d62e620f37f8fc55397222ceb68ca8387eb0503df7173782634" -sha512 = "997e336258dd3d8d1bf1b27463e77d1dc2160eb13fff899c93b446973f5efbc59448a23279b60568679c08e006a20cc88769ec74d6d30baa4e7a17df0bdb2c30" +sha256 = "5e7010b31fc80b5484cdcad7bfaae9dbb2134d3debfa6a90c69c30ec8cf7d55e" +sha512 = "3863bd53d4ef1815f0f0f48d4032e3232322a3dbfa875eb573df2940264aacfe55d672886323406e5942ffc38ed5ad7dce91fcff3ff1e2e072773bb6dd9c7cd1" diff --git a/proposals/http/wit-0.3.0-draft/types.wit b/proposals/http/wit-0.3.0-draft/types.wit index e19c3a5e..0d208fce 100644 --- a/proposals/http/wit-0.3.0-draft/types.wit +++ b/proposals/http/wit-0.3.0-draft/types.wit @@ -121,11 +121,6 @@ interface types { /// implementation-defined limit on field sizes. This may apply to /// an individual `field-value`, a single `field-name` plus all its /// values, or the total aggregate size of all fields. - /// - /// Implementations MUST accept individual field values of at least - /// 8192 bytes and total aggregate field sections of at least 16384 - /// bytes. These minimums ensure portability across common HTTP - /// servers and match HTTP/2's minimum SETTINGS_MAX_FRAME_SIZE. size-exceeded, /// This is a catch-all error for anything that doesn't fit cleanly into a @@ -188,9 +183,7 @@ interface types { /// /// Implementations may impose limits on individual field values and on total /// aggregate field section size. Operations that would exceed these limits - /// fail with `header-error.size-exceeded`. Implementations MUST accept - /// individual field values of at least 8192 bytes and total aggregate field - /// sections of at least 16384 bytes. + /// fail with `header-error.size-exceeded` @since(version = 0.3.0-rc-2026-02-09) resource fields {