From 49527e52f4500199c9c423ad6d6391132797a66b Mon Sep 17 00:00:00 2001 From: Bailey Hayes Date: Tue, 3 Mar 2026 14:17:32 -0500 Subject: [PATCH] doc(wasip2): note implementation limits may trap Document host resource limit behavior for WASIp2 interfaces. --- proposals/clocks/wit/monotonic-clock.wit | 10 ++++++++++ proposals/filesystem/wit/types.wit | 6 ++++++ proposals/http/wit/types.wit | 20 ++++++++++++++++++-- proposals/random/wit/insecure.wit | 4 ++++ proposals/random/wit/random.wit | 3 +++ 5 files changed, 41 insertions(+), 2 deletions(-) diff --git a/proposals/clocks/wit/monotonic-clock.wit b/proposals/clocks/wit/monotonic-clock.wit index b9ab7b49..fd110e51 100644 --- a/proposals/clocks/wit/monotonic-clock.wit +++ b/proposals/clocks/wit/monotonic-clock.wit @@ -41,6 +41,11 @@ interface monotonic-clock { /// Create a `pollable` which will resolve once the specified instant /// has occurred. + /// + /// Each call creates a new resource handle in the component's handle + /// table. Implementations may trap if the handle table is full. Guests + /// should drop `pollable` handles promptly after use and avoid creating + /// unbounded numbers of subscriptions. @since(version = 0.2.0) subscribe-instant: func( when: instant, @@ -48,6 +53,11 @@ interface monotonic-clock { /// Create a `pollable` that will resolve after the specified duration has /// elapsed from the time this function is invoked. + /// + /// Each call creates a new resource handle in the component's handle + /// table. Implementations may trap if the handle table is full. Guests + /// should drop `pollable` handles promptly after use and avoid creating + /// unbounded numbers of subscriptions. @since(version = 0.2.0) subscribe-duration: func( when: duration, diff --git a/proposals/filesystem/wit/types.wit b/proposals/filesystem/wit/types.wit index 374fbe38..a56369eb 100644 --- a/proposals/filesystem/wit/types.wit +++ b/proposals/filesystem/wit/types.wit @@ -407,6 +407,9 @@ interface types { /// /// In the future, this may change to return a `stream`. /// + /// Implementations may trap if `length` exceeds an + /// implementation-defined limit. + /// /// Note: This is similar to `pread` in POSIX. @since(version = 0.2.0) read: func( @@ -424,6 +427,9 @@ interface types { /// /// In the future, this may change to take a `stream`. /// + /// Implementations may trap if the buffer size exceeds an + /// implementation-defined limit. + /// /// Note: This is similar to `pwrite` in POSIX. @since(version = 0.2.0) write: func( diff --git a/proposals/http/wit/types.wit b/proposals/http/wit/types.wit index 657952f3..fca9e78c 100644 --- a/proposals/http/wit/types.wit +++ b/proposals/http/wit/types.wit @@ -122,6 +122,9 @@ interface types { /// This type enumerates the different kinds of errors that may occur when /// setting or appending to a `fields` resource. + /// + /// Note: Implementations may also trap when an operation would cause the + /// `fields` to exceed an implementation-defined size limit. @since(version = 0.2.0) variant header-error { /// This error indicates that a `field-name` or `field-value` was @@ -149,9 +152,9 @@ interface types { /// /// Field keys should always be treated as case insensitive by the `fields` /// resource for the purposes of equality checking. - /// + /// /// # Deprecation - /// + /// /// This type has been deprecated in favor of the `field-name` type. @since(version = 0.2.0) @deprecated(version = 0.2.2) @@ -173,6 +176,10 @@ interface types { /// `incoming-request.headers`, `outgoing-request.headers`) might be /// immutable. In an immutable fields, the `set`, `append`, and `delete` /// operations will fail with `header-error.immutable`. + /// + /// Implementations may impose limits on individual field values and on the + /// total aggregate field section size. Operations that would exceed these + /// limits may trap. @since(version = 0.2.0) resource fields { @@ -195,6 +202,9 @@ interface types { /// /// An error result will be returned if any `field-name` or `field-value` is /// syntactically invalid, or if a field is forbidden. + /// + /// Implementations may trap if the entries would exceed an + /// implementation-defined size limit. @since(version = 0.2.0) from-list: static func( entries: list> @@ -219,6 +229,9 @@ interface types { /// /// Fails with `header-error.invalid-syntax` if the `field-name` or any of /// the `field-value`s are syntactically invalid. + /// + /// Implementations may trap if the name or values would exceed an + /// implementation-defined size limit. @since(version = 0.2.0) set: func(name: field-name, value: list) -> result<_, header-error>; @@ -239,6 +252,9 @@ interface types { /// /// Fails with `header-error.invalid-syntax` if the `field-name` or /// `field-value` are syntactically invalid. + /// + /// Implementations may trap if the value would exceed an + /// implementation-defined size limit. @since(version = 0.2.0) append: func(name: field-name, value: field-value) -> result<_, header-error>; diff --git a/proposals/random/wit/insecure.wit b/proposals/random/wit/insecure.wit index 34d8a9e5..8042a855 100644 --- a/proposals/random/wit/insecure.wit +++ b/proposals/random/wit/insecure.wit @@ -13,6 +13,10 @@ interface insecure { /// There are no requirements on the values of the returned bytes, however /// implementations are encouraged to return evenly distributed values with /// a long period. + /// + /// Implementations may trap if `len` exceeds an implementation-defined + /// limit. Guests requiring more bytes should call this function multiple + /// times. @since(version = 0.2.0) get-insecure-random-bytes: func(len: u64) -> list; diff --git a/proposals/random/wit/random.wit b/proposals/random/wit/random.wit index d5d724ae..fa9afde8 100644 --- a/proposals/random/wit/random.wit +++ b/proposals/random/wit/random.wit @@ -17,6 +17,9 @@ interface random { /// This function must always return fresh data. Deterministic environments /// must omit this function, rather than implementing it with deterministic /// data. + /// + /// Implementations may trap if `len` exceeds an implementation-defined + /// limit. @since(version = 0.2.0) get-random-bytes: func(len: u64) -> list;