From 5e5c02669b75e1cd51f26d60e7c5a6ea61ce9ce9 Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 14 Aug 2024 14:19:54 +0200 Subject: [PATCH 01/10] Specify the casing of field keys and values The PR updating this only caught the 0.3-draft APIs, presumably by accident. Including it in this change since we're touching the header names already. --- wit/types.wit | 3 +++ 1 file changed, 3 insertions(+) diff --git a/wit/types.wit b/wit/types.wit index 3c45cd0..7148277 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -139,6 +139,9 @@ interface types { } /// Field keys are always strings. + /// + /// Field keys should always be treated as case insensitive by the `fields` + /// resource for the purposes of equality checking. @since(version = 0.2.0) type field-key = string; From 1b206d731d47f254439ef4beff93af8650fb67d6 Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 14 Aug 2024 14:20:28 +0200 Subject: [PATCH 02/10] deprecate `field-key` in favor of `field-name` --- proxy.md | 811 +++++++++++++++++++------------------- wit-0.3.0-draft/types.wit | 27 +- wit/types.wit | 41 +- 3 files changed, 452 insertions(+), 427 deletions(-) diff --git a/proxy.md b/proxy.md index a1d3f93..f019fb5 100644 --- a/proxy.md +++ b/proxy.md @@ -1,4 +1,4 @@ -

World proxy

+

World proxy

The wasi:http/proxy world captures a widely-implementable intersection of hosts that includes HTTP forward and reverse proxies. Components targeting this world may concurrently stream in and out any number of incoming and @@ -25,35 +25,35 @@ outgoing HTTP requests.

-

Import interface wasi:io/poll@0.2.1

+

Import interface wasi:io/poll@0.2.1

A poll API intended to let users wait for I/O events on multiple handles at once.

Types

-

resource pollable

+

resource pollable

pollable represents a single I/O event which may be ready, or not.

Functions

-

[method]pollable.ready: func

+

[method]pollable.ready: func

Return the readiness of a pollable. This function never blocks.

Returns true when the pollable is ready, and false otherwise.

Params
Return values
-

[method]pollable.block: func

+

[method]pollable.block: func

block returns immediately if the pollable is ready, and otherwise blocks until ready.

This function is equivalent to calling poll.poll on a list containing only this pollable.

Params
-

poll: func

+

poll: func

Poll for completion on a set of pollables.

This function takes a list of pollables, which identify I/O sources of interest, and waits until one or more of the events is ready for I/O.

@@ -72,13 +72,13 @@ the pollables has an error, it is indicated by marking the source as being ready for I/O.

Params
Return values
-

Import interface wasi:clocks/monotonic-clock@0.2.1

+

Import interface wasi:clocks/monotonic-clock@0.2.1

WASI Monotonic Clock is a clock API intended to let users measure elapsed time.

It is intended to be portable at least between Unix-family platforms and @@ -87,60 +87,60 @@ Windows.

successive reads of the clock will produce non-decreasing values.

Types

-

type pollable

+

type pollable

pollable

-#### `type instant` +#### `type instant` `u64`

An instant in time, in nanoseconds. An instant is relative to an unspecified initial value, and can only be compared to instances from the same monotonic-clock. -

type duration

+

type duration

u64

A duration of time, in nanoseconds.

Functions

-

now: func

+

now: func

Read the current value of the clock.

The clock is monotonic, therefore calling this function repeatedly will produce a sequence of non-decreasing values.

Return values
-

resolution: func

+

resolution: func

Query the resolution of the clock. Returns the duration of time corresponding to a clock tick.

Return values
-

subscribe-instant: func

+

subscribe-instant: func

Create a pollable which will resolve once the specified instant has occurred.

Params
Return values
-

subscribe-duration: func

+

subscribe-duration: func

Create a pollable that will resolve after the specified duration has elapsed from the time this function is invoked.

Params
Return values
-

Import interface wasi:io/error@0.2.1

+

Import interface wasi:io/error@0.2.1

Types

-

resource error

+

resource error

A resource which represents some error information.

The only method provided by this resource is to-debug-string, which provides some human-readable information about the error.

@@ -155,7 +155,7 @@ parameter and returns an option<wasi:filesystem/types/error-code>The set of functions which can "downcast" an error into a more concrete type is open.

Functions

-

[method]error.to-debug-string: func

+

[method]error.to-debug-string: func

Returns a string that is suitable to assist humans in debugging this error.

WARNING: The returned string should not be consumed mechanically! @@ -164,42 +164,42 @@ details. Parsing this string is a major platform-compatibility hazard.

Params
Return values
    -
  • string
    • +
  • string
-

Import interface wasi:io/streams@0.2.1

+

Import interface wasi:io/streams@0.2.1

WASI I/O is an I/O abstraction API which is currently focused on providing stream types.

In the future, the component model is expected to add built-in stream types; when it does, they are expected to subsume this API.

Types

-

type error

+

type error

error

-#### `type pollable` +#### `type pollable` [`pollable`](#pollable)

-#### `variant stream-error` +#### `variant stream-error`

An error for input-stream and output-stream operations.

Variant Cases
  • -

    last-operation-failed: own<error>

    +

    last-operation-failed: own<error>

    The last operation (a write or flush) failed before completion.

    More information is available in the error payload.

  • -

    closed

    +

    closed

    The stream is closed: no more input will be accepted by the stream. A closed output-stream will return this error on all future operations.

-

resource input-stream

+

resource input-stream

An input bytestream.

input-streams are non-blocking to the extent practical on underlying platforms. I/O operations always return promptly; if fewer bytes are @@ -207,7 +207,7 @@ promptly available than requested, they return the number of bytes promptly available, which could even be zero. To wait for data to be available, use the subscribe function to obtain a pollable which can be polled for using wasi:io/poll.

-

resource output-stream

+

resource output-stream

An output bytestream.

output-streams are non-blocking to the extent practical on underlying platforms. Except where specified otherwise, I/O operations also @@ -219,7 +219,7 @@ polled for using wasi:io/poll.

progress may result in the data being lost. Before dropping the stream, be sure to fully flush your writes.

Functions

-

[method]input-stream.read: func

+

[method]input-stream.read: func

Perform a non-blocking read from the stream.

When the source of a read is binary data, the bytes from the source are returned verbatim. When the source of a read is known to the @@ -243,51 +243,51 @@ as a return value by the callee. The callee may return a list of bytes less than len in size while more bytes are available for reading.

Params
Return values
-

[method]input-stream.blocking-read: func

+

[method]input-stream.blocking-read: func

Read bytes from a stream, after blocking until at least one byte can be read. Except for blocking, behavior is identical to read.

Params
Return values
-

[method]input-stream.skip: func

+

[method]input-stream.skip: func

Skip bytes from a stream. Returns number of bytes skipped.

Behaves identical to read, except instead of returning a list of bytes, returns the number of bytes consumed from the stream.

Params
Return values
-

[method]input-stream.blocking-skip: func

+

[method]input-stream.blocking-skip: func

Skip bytes from a stream, after blocking until at least one byte can be skipped. Except for blocking behavior, identical to skip.

Params
Return values
-

[method]input-stream.subscribe: func

+

[method]input-stream.subscribe: func

Create a pollable which will resolve once either the specified stream has bytes available to read or the other end of the stream has been closed. @@ -296,13 +296,13 @@ Implementations may trap if the input-streampollables created with this function are dropped.

Params
Return values
-

[method]output-stream.check-write: func

+

[method]output-stream.check-write: func

Check readiness for writing. This function never blocks.

Returns the number of bytes permitted for the next call to write, or an error. Calling write with more bytes than this function has @@ -312,13 +312,13 @@ become ready when this function will report at least 1 byte, or an error.

Params
Return values
-

[method]output-stream.write: func

+

[method]output-stream.write: func

Perform a write. This function never blocks.

When the destination of a write is binary data, the bytes from contents are written verbatim. When the destination of a write is @@ -331,14 +331,14 @@ length of less than or equal to n. Otherwise, this function will trap.

the last call to check-write provided a permit.

Params
Return values
-

[method]output-stream.blocking-write-and-flush: func

+

[method]output-stream.blocking-write-and-flush: func

Perform a write of up to 4096 bytes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

This is a convenience wrapper around the use of check-write, @@ -362,14 +362,14 @@ let _ = this.check-write(); // eliding error handling

Params
Return values
-

[method]output-stream.flush: func

+

[method]output-stream.flush: func

Request to flush buffered output. This function never blocks.

This tells the output-stream that the caller intends any buffered output to be flushed. the output which is expected to be flushed @@ -380,24 +380,24 @@ completed. The subscribe pollable will become ready when the flush has completed and the stream can accept more writes.

Params
Return values
-

[method]output-stream.blocking-flush: func

+

[method]output-stream.blocking-flush: func

Request to flush buffered output, and block until flush completes and stream is ready for writing again.

Params
Return values
-

[method]output-stream.subscribe: func

+

[method]output-stream.subscribe: func

Create a pollable which will resolve once the output-stream is ready for more writing, or an error has occurred. When this pollable is ready, check-write will return ok(n) with n>0, or an @@ -408,13 +408,13 @@ Implementations may trap if the output-streampollables created with this function are dropped.

Params
Return values
-

[method]output-stream.write-zeroes: func

+

[method]output-stream.write-zeroes: func

Write zeroes to a stream.

This should be used precisely like write with the exact same preconditions (must use check-write first), but instead of @@ -422,14 +422,14 @@ passing a list of bytes, you simply pass the number of zero-bytes that should be written.

Params
Return values
-

[method]output-stream.blocking-write-zeroes-and-flush: func

+

[method]output-stream.blocking-write-zeroes-and-flush: func

Perform a write of up to 4096 zeroes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

@@ -453,14 +453,14 @@ let _ = this.check-write(); // eliding error handling
Params
Return values
-

[method]output-stream.splice: func

+

[method]output-stream.splice: func

Read from one stream and write to another.

The behavior of splice is equivalent to:

    @@ -475,175 +475,184 @@ let _ = this.check-write(); // eliding error handling than len.

    Params
    Return values
    -

    [method]output-stream.blocking-splice: func

    +

    [method]output-stream.blocking-splice: func

    Read from one stream and write to another, with blocking.

    This is similar to splice, except that it blocks until the output-stream is ready for writing, and the input-stream is ready for reading, before performing the splice.

    Params
    Return values
    -

    Import interface wasi:http/types@0.2.1

    +

    Import interface wasi:http/types@0.2.1

    This interface defines all of the types and methods for implementing HTTP Requests and Responses, both incoming and outgoing, as well as their headers, trailers, and bodies.

    Types

    -

    type duration

    +

    type duration

    duration

    -#### `type input-stream` +#### `type input-stream` [`input-stream`](#input_stream)

    -#### `type output-stream` +#### `type output-stream` [`output-stream`](#output_stream)

    -#### `type io-error` +#### `type io-error` [`error`](#error)

    -#### `type pollable` +#### `type pollable` [`pollable`](#pollable)

    -#### `variant method` +#### `variant method`

    This type corresponds to HTTP standard Methods.

    Variant Cases
      -
    • get
      • -
    • head
      • -
    • post
      • -
    • put
      • -
    • delete
      • -
    • connect
      • -
    • options
      • -
    • trace
      • -
    • patch
      • -
    • other: string
      • -
    -

    variant scheme

    +
  1. get
    2. +
  2. head
    3. +
  3. post
    4. +
  4. put
    5. +
  5. delete
    6. +
  6. connect
    7. +
  7. options
    8. +
  8. trace
    9. +
  9. patch
    10. +
  10. other: string
    11. + +

    variant scheme

    This type corresponds to HTTP standard Related Schemes.

    Variant Cases
      -
    • HTTP
      • -
    • HTTPS
      • -
    • other: string
      • +
    • HTTP
      • +
    • HTTPS
      • +
    • other: string
    -

    record DNS-error-payload

    +

    record DNS-error-payload

    Defines the case payload type for DNS-error above:

    Record Fields
      -
    • rcode: option<string>
      • -
    • info-code: option<u16>
      • +
    • rcode: option<string>
      • +
    • info-code: option<u16>
    -

    record TLS-alert-received-payload

    +

    record TLS-alert-received-payload

    Defines the case payload type for TLS-alert-received above:

    Record Fields
      -
    • alert-id: option<u8>
      • -
    • alert-message: option<string>
      • +
    • alert-id: option<u8>
      • +
    • alert-message: option<string>
    -

    record field-size-payload

    +

    record field-size-payload

    Defines the case payload type for HTTP-response-{header,trailer}-size above:

    Record Fields
      -
    • field-name: option<string>
      • -
    • field-size: option<u32>
      • +
    • field-name: option<string>
      • +
    • field-size: option<u32>
    -

    variant error-code

    +

    variant error-code

    These cases are inspired by the IANA HTTP Proxy Error Types: https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types

    Variant Cases
      -
    • DNS-timeout
      • -
    • DNS-error: DNS-error-payload
      • -
    • destination-not-found
      • -
    • destination-unavailable
      • -
    • destination-IP-prohibited
      • -
    • destination-IP-unroutable
      • -
    • connection-refused
      • -
    • connection-terminated
      • -
    • connection-timeout
      • -
    • connection-read-timeout
      • -
    • connection-write-timeout
      • -
    • connection-limit-reached
      • -
    • TLS-protocol-error
      • -
    • TLS-certificate-error
      • -
    • TLS-alert-received: TLS-alert-received-payload
      • -
    • HTTP-request-denied
      • -
    • HTTP-request-length-required
      • -
    • HTTP-request-body-size: option<u64>
      • -
    • HTTP-request-method-invalid
      • -
    • HTTP-request-URI-invalid
      • -
    • HTTP-request-URI-too-long
      • -
    • HTTP-request-header-section-size: option<u32>
      • -
    • HTTP-request-header-size: option<field-size-payload>
      • -
    • HTTP-request-trailer-section-size: option<u32>
      • -
    • HTTP-request-trailer-size: field-size-payload
      • -
    • HTTP-response-incomplete
      • -
    • HTTP-response-header-section-size: option<u32>
      • -
    • HTTP-response-header-size: field-size-payload
      • -
    • HTTP-response-body-size: option<u64>
      • -
    • HTTP-response-trailer-section-size: option<u32>
      • -
    • HTTP-response-trailer-size: field-size-payload
      • -
    • HTTP-response-transfer-coding: option<string>
      • -
    • HTTP-response-content-coding: option<string>
      • -
    • HTTP-response-timeout
      • -
    • HTTP-upgrade-failed
      • -
    • HTTP-protocol-error
      • -
    • loop-detected
      • -
    • configuration-error
      • -
    • internal-error: option<string>

      This is a catch-all error for anything that doesn't fit cleanly into a +

    • DNS-timeout
      • +
    • DNS-error: DNS-error-payload
      • +
    • destination-not-found
      • +
    • destination-unavailable
      • +
    • destination-IP-prohibited
      • +
    • destination-IP-unroutable
      • +
    • connection-refused
      • +
    • connection-terminated
      • +
    • connection-timeout
      • +
    • connection-read-timeout
      • +
    • connection-write-timeout
      • +
    • connection-limit-reached
      • +
    • TLS-protocol-error
      • +
    • TLS-certificate-error
      • +
    • TLS-alert-received: TLS-alert-received-payload
      • +
    • HTTP-request-denied
      • +
    • HTTP-request-length-required
      • +
    • HTTP-request-body-size: option<u64>
      • +
    • HTTP-request-method-invalid
      • +
    • HTTP-request-URI-invalid
      • +
    • HTTP-request-URI-too-long
      • +
    • HTTP-request-header-section-size: option<u32>
      • +
    • HTTP-request-header-size: option<field-size-payload>
      • +
    • HTTP-request-trailer-section-size: option<u32>
      • +
    • HTTP-request-trailer-size: field-size-payload
      • +
    • HTTP-response-incomplete
      • +
    • HTTP-response-header-section-size: option<u32>
      • +
    • HTTP-response-header-size: field-size-payload
      • +
    • HTTP-response-body-size: option<u64>
      • +
    • HTTP-response-trailer-section-size: option<u32>
      • +
    • HTTP-response-trailer-size: field-size-payload
      • +
    • HTTP-response-transfer-coding: option<string>
      • +
    • HTTP-response-content-coding: option<string>
      • +
    • HTTP-response-timeout
      • +
    • HTTP-upgrade-failed
      • +
    • HTTP-protocol-error
      • +
    • loop-detected
      • +
    • configuration-error
      • +
    • internal-error: option<string>

      This is a catch-all error for anything that doesn't fit cleanly into a more specific case. 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.

    -

    variant header-error

    +

    variant header-error

    This type enumerates the different kinds of errors that may occur when setting or appending to a fields resource.

    Variant Cases
    • -

      invalid-syntax

      -

      This error indicates that a `field-key` or `field-value` was +

      invalid-syntax

      +

      This error indicates that a `field-name` or `field-value` was syntactically invalid when used with an operation that sets headers in a `fields`.

    • -

      forbidden

      -

      This error indicates that a forbidden `field-key` was used when trying +

      forbidden

      +

      This error indicates that a forbidden `field-name` was used when trying to set a header in a `fields`.

    • -

      immutable

      +

      immutable

      This error indicates that the operation on the `fields` was not permitted because the fields are immutable.

    -

    type field-key

    +

    type field-key

    string

    Field keys are always strings. -

    type field-value

    +

    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.

    +

    type field-name

    +

    field-key

    +

    Field names are always strings. +

    Field keys should always be treated as case insensitive by the fields +resource for the purposes of equality checking.

    +

    type field-value

    field-value

    Field values should always be ASCII strings. However, in reality, HTTP implementations often have to interpret malformed values, so they are provided as a list of bytes. -

    resource fields

    +

    resource fields

    This following block defines the fields resource which corresponds to HTTP standard Fields. Fields are a common representation used for both Headers and Trailers.

    @@ -653,33 +662,33 @@ resource given by other means (including, but not limited to, incoming-request.headers, outgoing-request.headers) might be be immutable. In an immutable fields, the set, append, and delete operations will fail with header-error.immutable.

    -

    type headers

    +

    type headers

    fields

    Headers is an alias for Fields. -

    type trailers

    +

    type trailers

    fields

    Trailers is an alias for Fields. -

    resource incoming-request

    +

    resource incoming-request

    Represents an incoming HTTP Request.

    -

    resource outgoing-request

    +

    resource outgoing-request

    Represents an outgoing HTTP Request.

    -

    resource request-options

    +

    resource request-options

    Parameters for making an HTTP Request. Each of these parameters is currently an optional timeout applicable to the transport layer of the HTTP protocol.

    These timeouts are separate from any the user may use to bound a blocking call to wasi:io/poll.poll.

    -

    resource response-outparam

    +

    resource response-outparam

    Represents the ability to send an HTTP Response.

    This resource is used by the wasi:http/incoming-handler interface to allow a Response to be sent corresponding to the Request provided as the other argument to incoming-handler.handle.

    -

    type status-code

    +

    type status-code

    u16

    This type corresponds to the HTTP standard Status Code. -

    resource incoming-response

    +

    resource incoming-response

    Represents an incoming HTTP Response.

    -

    resource incoming-body

    +

    resource incoming-body

    Represents an incoming HTTP Request or Response's Body.

    A body has both its contents - a stream of bytes - and a (possibly empty) set of trailers, indicating that the full contents of the @@ -687,14 +696,14 @@ body have been received. This resource represents the contents as an input-stream and the delivery of trailers as a future-trailers, and ensures that the user of this interface may only be consuming either the body contents or waiting on trailers at any given time.

    -

    resource future-trailers

    +

    resource future-trailers

    Represents a future which may eventually return trailers, or an error.

    In the case that the incoming HTTP Request or Response did not have any trailers, this future will resolve to the empty set of trailers once the complete Request or Response body has been received.

    -

    resource outgoing-response

    +

    resource outgoing-response

    Represents an outgoing HTTP Response.

    -

    resource outgoing-body

    +

    resource outgoing-body

    Represents an outgoing HTTP Request or Response's Body.

    A body has both its contents - a stream of bytes - and a (possibly empty) set of trailers, inducating the full contents of the body @@ -709,13 +718,13 @@ and that an error has occurred. The implementation should propagate this error to the HTTP protocol by whatever means it has available, including: corrupting the body on the wire, aborting the associated Request, or sending a late status code for the Response.

    -

    resource future-incoming-response

    +

    resource future-incoming-response

    Represents a future which may eventually return an incoming HTTP Response, or an error.

    This resource is returned by the wasi:http/outgoing-handler interface to provide the HTTP Response corresponding to the sent Request.

    Functions

    -

    http-error-code: func

    +

    http-error-code: func

    Attempts to extract a http-related error from the wasi:io error provided.

    Stream operations which return @@ -727,20 +736,20 @@ if there's http-related information about the error to return.

    http-related errors.

    Params
    Return values
    -

    [constructor]fields: func

    +

    [constructor]fields: func

    Construct an empty HTTP Fields.

    The resulting fields is mutable.

    Return values
    -

    [static]fields.from-list: func

    +

    [static]fields.from-list: func

    Construct an HTTP Fields.

    The resulting fields is mutable.

    The list represents each key-value pair in the Fields. Keys @@ -748,156 +757,158 @@ which have multiple values are represented by multiple entries in this list with the same key.

    The tuple is a pair of the field key, represented as a string, and Value, represented as a list of bytes.

    -

    An error result will be returned if any field-key or field-value is +

    An error result will be returned if any field-name or field-value is syntactically invalid, or if a field is forbidden.

    Params
    Return values
    -

    [method]fields.get: func

    +

    [method]fields.get: func

    Get all of the values corresponding to a key. If the key is not present in this fields or is syntactically invalid, an empty list is returned. However, if the key is present but empty, this is represented by a list with one or more empty field-values present.

    Params
    Return values
    -

    [method]fields.has: func

    +

    [method]fields.has: func

    Returns true when the key is present in this fields. If the key is syntactically invalid, false is returned.

    Params
    Return values
      -
    • bool
      • +
    • bool
    -

    [method]fields.set: func

    +

    [method]fields.set: func

    Set all of the values for a key. Clears any existing values for that key, if they have been set.

    Fails with header-error.immutable if the fields are immutable.

    -

    Fails with header-error.invalid-syntax if the field-key or any of +

    Fails with header-error.invalid-syntax if the field-name or any of the field-values are syntactically invalid.

    Params
    Return values
    -

    [method]fields.delete: func

    +

    [method]fields.delete: func

    Delete all values for a key. Does nothing if no values for the key exist.

    Fails with header-error.immutable if the fields are immutable.

    -

    Fails with header-error.invalid-syntax if the field-key is +

    Fails with header-error.invalid-syntax if the field-name is syntactically invalid.

    Params
    Return values
    -

    [method]fields.append: func

    +

    [method]fields.append: func

    Append a value for a key. Does not change or delete any existing values for that key.

    Fails with header-error.immutable if the fields are immutable.

    -

    Fails with header-error.invalid-syntax if the field-key or +

    Fails with header-error.invalid-syntax if the field-name or field-value are syntactically invalid.

    Params
    Return values
    -

    [method]fields.entries: func

    +

    [method]fields.entries: func

    Retrieve the full set of keys and values in the Fields. Like the constructor, the list represents each key-value pair.

    The outer list represents each key-value pair in the Fields. Keys which have multiple values are represented by multiple entries in this list with the same key.

    +

    The keys and values are always returned in the original casing and in +the order in which they will be serialized for transport.

    Params
    Return values
    -

    [method]fields.clone: func

    +

    [method]fields.clone: func

    Make a deep copy of the Fields. Equivalent in behavior to calling the fields constructor on the return value of entries. The resulting fields is mutable.

    Params
    Return values
    -

    [method]incoming-request.method: func

    +

    [method]incoming-request.method: func

    Returns the method of the incoming request.

    Params
    Return values
    -

    [method]incoming-request.path-with-query: func

    +

    [method]incoming-request.path-with-query: func

    Returns the path with query parameters from the request, as a string.

    Params
    Return values
      -
    • option<string>
      • +
    • option<string>
    -

    [method]incoming-request.scheme: func

    +

    [method]incoming-request.scheme: func

    Returns the protocol scheme from the request.

    Params
    Return values
    -

    [method]incoming-request.authority: func

    +

    [method]incoming-request.authority: func

    Returns the authority of the Request's target URI, if present.

    Params
    Return values
      -
    • option<string>
      • +
    • option<string>
    -

    [method]incoming-request.headers: func

    +

    [method]incoming-request.headers: func

    Get the headers associated with the request.

    The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

    @@ -906,24 +917,24 @@ the parent incoming-request is drop incoming-request before all children are dropped will trap.

    Params
    Return values
    -

    [method]incoming-request.consume: func

    +

    [method]incoming-request.consume: func

    Gives the incoming-body associated with this request. Will only return success at most once, and subsequent calls will return error.

    Params
    Return values
    -

    [constructor]outgoing-request: func

    +

    [constructor]outgoing-request: func

    Construct a new outgoing-request with a default method of GET, and none values for path-with-query, scheme, and authority.

      @@ -936,13 +947,13 @@ It is the obligation of the outgoing-handler.handle implementation to reject invalid constructions of outgoing-request.

      Params
      Return values
      -

      [method]outgoing-request.body: func

      +

      [method]outgoing-request.body: func

      Returns the resource corresponding to the outgoing Body for this Request.

      Returns success on the first call: the outgoing-body resource for @@ -950,109 +961,109 @@ this outgoing-request can be retrie calls will return error.

      Params
      Return values
      -

      [method]outgoing-request.method: func

      +

      [method]outgoing-request.method: func

      Get the Method for the Request.

      Params
      Return values
      -

      [method]outgoing-request.set-method: func

      +

      [method]outgoing-request.set-method: func

      Set the Method for the Request. Fails if the string present in a method.other argument is not a syntactically valid method.

      Params
      Return values
        -
      • result
        • +
      • result
      -

      [method]outgoing-request.path-with-query: func

      +

      [method]outgoing-request.path-with-query: func

      Get the combination of the HTTP Path and Query for the Request. When none, this represents an empty Path and empty Query.

      Params
      Return values
        -
      • option<string>
        • +
      • option<string>
      -

      [method]outgoing-request.set-path-with-query: func

      +

      [method]outgoing-request.set-path-with-query: func

      Set the combination of the HTTP Path and Query for the Request. When none, this represents an empty Path and empty Query. Fails is the string given is not a syntactically valid path and query uri component.

      Params
      Return values
        -
      • result
        • +
      • result
      -

      [method]outgoing-request.scheme: func

      +

      [method]outgoing-request.scheme: func

      Get the HTTP Related Scheme for the Request. When none, the implementation may choose an appropriate default scheme.

      Params
      Return values
      -

      [method]outgoing-request.set-scheme: func

      +

      [method]outgoing-request.set-scheme: func

      Set the HTTP Related Scheme for the Request. When none, the implementation may choose an appropriate default scheme. Fails if the string given is not a syntactically valid uri scheme.

      Params
      Return values
        -
      • result
        • +
      • result
      -

      [method]outgoing-request.authority: func

      +

      [method]outgoing-request.authority: func

      Get the authority of the Request's target URI. A value of none may be used with Related Schemes which do not require an authority. The HTTP and HTTPS schemes always require an authority.

      Params
      Return values
        -
      • option<string>
        • +
      • option<string>
      -

      [method]outgoing-request.set-authority: func

      +

      [method]outgoing-request.set-authority: func

      Set the authority of the Request's target URI. A value of none may be used with Related Schemes which do not require an authority. The HTTP and HTTPS schemes always require an authority. Fails if the string given is not a syntactically valid URI authority.

      Params
      Return values
        -
      • result
        • +
      • result
      -

      [method]outgoing-request.headers: func

      +

      [method]outgoing-request.headers: func

      Get the headers associated with the Request.

      The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

      @@ -1061,87 +1072,87 @@ not a syntactically valid URI authority.

      another component by e.g. outgoing-handler.handle.

      Params
      Return values
      -

      [constructor]request-options: func

      +

      [constructor]request-options: func

      Construct a default request-options value.

      Return values
      -

      [method]request-options.connect-timeout: func

      +

      [method]request-options.connect-timeout: func

      The timeout for the initial connect to the HTTP Server.

      Params
      Return values
      -

      [method]request-options.set-connect-timeout: func

      +

      [method]request-options.set-connect-timeout: func

      Set the timeout for the initial connect to the HTTP Server. An error return value indicates that this timeout is not supported.

      Params
      Return values
        -
      • result
        • +
      • result
      -

      [method]request-options.first-byte-timeout: func

      +

      [method]request-options.first-byte-timeout: func

      The timeout for receiving the first byte of the Response body.

      Params
      Return values
      -

      [method]request-options.set-first-byte-timeout: func

      +

      [method]request-options.set-first-byte-timeout: func

      Set the timeout for receiving the first byte of the Response body. An error return value indicates that this timeout is not supported.

      Params
      Return values
        -
      • result
        • +
      • result
      -

      [method]request-options.between-bytes-timeout: func

      +

      [method]request-options.between-bytes-timeout: func

      The timeout for receiving subsequent chunks of bytes in the Response body stream.

      Params
      Return values
      -

      [method]request-options.set-between-bytes-timeout: func

      +

      [method]request-options.set-between-bytes-timeout: func

      Set the timeout for receiving subsequent chunks of bytes in the Response body stream. An error return value indicates that this timeout is not supported.

      Params
      Return values
        -
      • result
        • +
      • result
      -

      [static]response-outparam.set: func

      +

      [static]response-outparam.set: func

      Set the value of the response-outparam to either send a response, or indicate an error.

      This method consumes the response-outparam to ensure that it is @@ -1151,20 +1162,20 @@ will respond with an error.

      implementation determine how to respond with an HTTP error response.

      Params
      -

      [method]incoming-response.status: func

      +

      [method]incoming-response.status: func

      Returns the status code from the incoming response.

      Params
      Return values
      -

      [method]incoming-response.headers: func

      +

      [method]incoming-response.headers: func

      Returns the headers from the incoming response.

      The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

      @@ -1172,24 +1183,24 @@ implementation determine how to respond with an HTTP error response.

      incoming-response is dropped.

      Params
      Return values
      -

      [method]incoming-response.consume: func

      +

      [method]incoming-response.consume: func

      Returns the incoming body. May be called at most once. Returns error if called additional times.

      Params
      Return values
      -

      [method]incoming-body.stream: func

      +

      [method]incoming-body.stream: func

      Returns the contents of the body, as a stream of bytes.

      Returns success on first call: the stream representing the contents can be retrieved at most once. Subsequent calls will return error.

      @@ -1204,36 +1215,36 @@ and for that backpressure to not inhibit delivery of the trailers if the user does not read the entire body.

      Params
      Return values
      -

      [static]incoming-body.finish: func

      +

      [static]incoming-body.finish: func

      Takes ownership of incoming-body, and returns a future-trailers. This function will trap if the input-stream child is still alive.

      Params
      Return values
      -

      [method]future-trailers.subscribe: func

      +

      [method]future-trailers.subscribe: func

      Returns a pollable which becomes ready when either the trailers have been received, or an error has occurred. When this pollable is ready, the get method will return some.

      Params
      Return values
      -

      [method]future-trailers.get: func

      +

      [method]future-trailers.get: func

      Returns the contents of the trailers, or an error which occurred, once the future is ready.

      The outer option represents future readiness. Users can wait on this @@ -1251,13 +1262,13 @@ resource is immutable, and a child. Use of the set, appendfuture-trailers is dropped.

      Params
      Return values
      -

      [constructor]outgoing-response: func

      +

      [constructor]outgoing-response: func

      Construct an outgoing-response, with a default status-code of 200. If a different status-code is needed, it must be set via the set-status-code method.

      @@ -1266,35 +1277,35 @@ If a different status-code is needed, it
    Params
    Return values
    -

    [method]outgoing-response.status-code: func

    +

    [method]outgoing-response.status-code: func

    Get the HTTP Status Code for the Response.

    Params
    Return values
    -

    [method]outgoing-response.set-status-code: func

    +

    [method]outgoing-response.set-status-code: func

    Set the HTTP Status Code for the Response. Fails if the status-code given is not a valid http status code.

    Params
    Return values
      -
    • result
      • +
    • result
    -

    [method]outgoing-response.headers: func

    +

    [method]outgoing-response.headers: func

    Get the headers associated with the Request.

    The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

    @@ -1303,26 +1314,26 @@ given is not a valid http status code.

    another component by e.g. outgoing-handler.handle.

    Params
    Return values
    -

    [method]outgoing-response.body: func

    +

    [method]outgoing-response.body: func

    Returns the resource corresponding to the outgoing Body for this Response.

    Returns success on the first call: the outgoing-body resource for this outgoing-response can be retrieved at most once. Subsequent calls will return error.

    Params
    Return values
    -

    [method]outgoing-body.write: func

    +

    [method]outgoing-body.write: func

    Returns a stream for writing the body contents.

    The returned output-stream is a child resource: it must be dropped before the parent outgoing-body resource is dropped (or finished), @@ -1332,13 +1343,13 @@ this outgoing-body may be retrieved at will return error.

    Params
    Return values
    -

    [static]outgoing-body.finish: func

    +

    [static]outgoing-body.finish: func

    Finalize an outgoing body, optionally providing trailers. This must be called to signal that the response is complete. If the outgoing-body is dropped without calling outgoing-body.finalize, the implementation @@ -1349,26 +1360,26 @@ to the body (via write) does not match the value given in the Content-Length.

    Params
    Return values
    -

    [method]future-incoming-response.subscribe: func

    +

    [method]future-incoming-response.subscribe: func

    Returns a pollable which becomes ready when either the Response has been received, or an error has occurred. When this pollable is ready, the get method will return some.

    Params
    Return values
    -

    [method]future-incoming-response.get: func

    +

    [method]future-incoming-response.get: func

    Returns the incoming HTTP Response, or an error, once one is ready.

    The outer option represents future readiness. Users can wait on this option to become some using the subscribe method.

    @@ -1382,13 +1393,13 @@ but those will be reported by the incoming-bodyoutput-stream child.

    Params
    Return values
    -

    Import interface wasi:clocks/wall-clock@0.2.1

    +

    Import interface wasi:clocks/wall-clock@0.2.1

    WASI Wall Clock is a clock API intended to let users query the current time. The name "wall" makes an analogy to a "clock on the wall", which is not necessarily monotonic as it may be reset.

    @@ -1401,16 +1412,16 @@ monotonic, making it unsuitable for measuring elapsed time.

    It is intended for reporting the current date and time for humans.

    Types

    -

    record datetime

    +

    record datetime

    A time and date in seconds plus nanoseconds.

    Record Fields
      -
    • seconds: u64
      • -
    • nanoseconds: u32
      • +
    • seconds: u64
      • +
    • nanoseconds: u32

    Functions

    -

    now: func

    +

    now: func

    Read the current value of the clock.

    This clock is not monotonic, therefore calling this function repeatedly will not necessarily produce a sequence of non-decreasing values.

    @@ -1420,22 +1431,22 @@ also known as Unix Time.The nanoseconds field of the output is always less than 1000000000.

    Return values
    -

    resolution: func

    +

    resolution: func

    Query the resolution of the clock.

    The nanoseconds field of the output is always less than 1000000000.

    Return values
    -

    Import interface wasi:random/random@0.2.1

    +

    Import interface wasi:random/random@0.2.1

    WASI Random is a random data API.

    It is intended to be portable at least between Unix-family platforms and Windows.

    Functions

    -

    get-random-bytes: func

    +

    get-random-bytes: func

    Return len cryptographically-secure random or pseudo-random bytes.

    This function must produce data at least as cryptographically secure and fast as an adequately seeded cryptographically-secure pseudo-random @@ -1448,79 +1459,79 @@ must omit this function, rather than implementing it with deterministic data.

    Params
      -
    • len: u64
      • +
    • len: u64
    Return values
      -
    • list<u8>
      • +
    • list<u8>
    -

    get-random-u64: func

    +

    get-random-u64: func

    Return a cryptographically-secure random or pseudo-random u64 value.

    This function returns the same type of data as get-random-bytes, represented as a u64.

    Return values
      -
    • u64
      • +
    • u64
    -

    Import interface wasi:cli/stdout@0.2.1

    +

    Import interface wasi:cli/stdout@0.2.1

    Types

    -

    type output-stream

    +

    type output-stream

    output-stream

    ----

    Functions

    -

    get-stdout: func

    +

    get-stdout: func

    Return values
    -

    Import interface wasi:cli/stderr@0.2.1

    +

    Import interface wasi:cli/stderr@0.2.1

    Types

    -

    type output-stream

    +

    type output-stream

    output-stream

    ----

    Functions

    -

    get-stderr: func

    +

    get-stderr: func

    Return values
    -

    Import interface wasi:cli/stdin@0.2.1

    +

    Import interface wasi:cli/stdin@0.2.1

    Types

    -

    type input-stream

    +

    type input-stream

    input-stream

    ----

    Functions

    -

    get-stdin: func

    +

    get-stdin: func

    Return values
    -

    Import interface wasi:http/outgoing-handler@0.2.1

    +

    Import interface wasi:http/outgoing-handler@0.2.1

    This interface defines a handler of outgoing HTTP Requests. It should be imported by components which wish to make HTTP Requests.

    Types

    -

    type outgoing-request

    +

    type outgoing-request

    outgoing-request

    -#### `type request-options` +#### `type request-options` [`request-options`](#request_options)

    -#### `type future-incoming-response` +#### `type future-incoming-response` [`future-incoming-response`](#future_incoming_response)

    -#### `type error-code` +#### `type error-code` [`error-code`](#error_code)

    ----

    Functions

    -

    handle: func

    +

    handle: func

    This function is invoked with an outgoing HTTP Request, and it returns a resource future-incoming-response which represents an HTTP Response which may arrive in the future.

    @@ -1531,25 +1542,25 @@ or not allowed to be made. Otherwise, protocol errors are reported through the future-incoming-response.

    Params
    Return values
    -

    Export interface wasi:http/incoming-handler@0.2.1

    +

    Export interface wasi:http/incoming-handler@0.2.1

    Types

    -

    type incoming-request

    +

    type incoming-request

    incoming-request

    -#### `type response-outparam` +#### `type response-outparam` [`response-outparam`](#response_outparam)

    ----

    Functions

    -

    handle: func

    +

    handle: func

    This function is invoked with an incoming HTTP Request, and a resource response-outparam which provides the capability to reply with an HTTP Response. The response is sent by calling the response-outparam.set @@ -1561,6 +1572,6 @@ work.

    with an error on its behalf.

    Params
    diff --git a/wit-0.3.0-draft/types.wit b/wit-0.3.0-draft/types.wit index da636bc..e562d8d 100644 --- a/wit-0.3.0-draft/types.wit +++ b/wit-0.3.0-draft/types.wit @@ -107,12 +107,12 @@ interface types { /// This type enumerates the different kinds of errors that may occur when /// setting or appending to a `fields` resource. variant header-error { - /// This error indicates that a `field-key` or `field-value` was + /// This error indicates that a `field-name` or `field-value` was /// syntactically invalid when used with an operation that sets headers in a /// `fields`. invalid-syntax, - /// This error indicates that a forbidden `field-key` was used when trying + /// This error indicates that a forbidden `field-name` was used when trying /// to set a header in a `fields`. forbidden, @@ -132,11 +132,11 @@ interface types { immutable, } - /// Field keys are always strings. + /// Field names are always strings. /// /// Field keys should always be treated as case insensitive by the `fields` /// resource for the purposes of equality checking. - type field-key = string; + type field-name = string; /// Field values should always be ASCII strings. However, in /// reality, HTTP implementations often have to interpret malformed values, @@ -154,8 +154,7 @@ interface types { /// `set`, `append`, and `delete` operations will fail with /// `header-error.immutable`. /// - /// A `fields` resource should store `field-key`s and `field-value`s in their - /// original casing used to construct or mutate the `fields` resource. The `fields` + /// A `fields` resource should store `field-name`s and `field-value`s in their /// 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. resource fields { @@ -181,30 +180,30 @@ interface types { /// An error result will be returned if any header or value was /// syntactically invalid, or if a header was forbidden. from-list: static func( - entries: list> + entries: list> ) -> result; /// Get all of the values corresponding to a key. If the key is not present /// in this `fields`, an empty list is returned. However, if the key is /// present but empty, this is represented by a list with one or more /// empty field-values present. - get: func(name: field-key) -> list; + get: func(name: field-name) -> list; /// Returns `true` when the key is present in this `fields`. If the key is /// syntactically invalid, `false` is returned. - has: func(name: field-key) -> bool; + has: func(name: field-name) -> bool; /// Set all of the values for a key. Clears any existing values for that /// key, if they have been set. /// /// Fails with `header-error.immutable` if the `fields` are immutable. - set: func(name: field-key, value: list) -> result<_, header-error>; + set: func(name: field-name, value: list) -> result<_, header-error>; /// Delete all values for a key. Does nothing if no values for the key /// exist. /// /// Fails with `header-error.immutable` if the `fields` are immutable. - delete: func(name: field-key) -> result<_, header-error>; + delete: func(name: field-name) -> result<_, header-error>; /// Delete all values for a key. Does nothing if no values for the key /// exist. @@ -212,13 +211,13 @@ interface types { /// Returns all values previously corresponding to the key, if any. /// /// Fails with `header-error.immutable` if the `fields` are immutable. - get-and-delete: func(name: field-key) -> result, header-error>; + get-and-delete: func(name: field-name) -> result, header-error>; /// Append a value for a key. Does not change or delete any existing /// values for that key. /// /// Fails with `header-error.immutable` if the `fields` are immutable. - append: func(name: field-key, value: field-value) -> result<_, header-error>; + append: func(name: field-name, value: field-value) -> result<_, header-error>; /// Retrieve the full set of keys and values in the Fields. Like the /// constructor, the list represents each key-value pair. @@ -229,7 +228,7 @@ interface types { /// /// The keys and values are always returned in the original casing and in /// the order in which they will be serialized for transport. - entries: func() -> list>; + entries: func() -> list>; /// Make a deep copy of the Fields. Equivalent in behavior to calling the /// `fields` constructor on the return value of `entries`. The resulting diff --git a/wit/types.wit b/wit/types.wit index 7148277..5836a9c 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -124,12 +124,12 @@ interface types { /// setting or appending to a `fields` resource. @since(version = 0.2.0) variant header-error { - /// This error indicates that a `field-key` or `field-value` was + /// This error indicates that a `field-name` or `field-value` was /// syntactically invalid when used with an operation that sets headers in a /// `fields`. invalid-syntax, - /// This error indicates that a forbidden `field-key` was used when trying + /// This error indicates that a forbidden `field-name` was used when trying /// to set a header in a `fields`. forbidden, @@ -138,11 +138,23 @@ interface types { immutable, } + /// Field names are always strings. + /// + /// Field keys should always be treated as case insensitive by the `fields` + /// resource for the purposes of equality checking. + @since(version = 0.2.1) + type field-name = field-key; + /// Field keys are always strings. /// /// 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.1) type field-key = string; /// Field values should always be ASCII strings. However, in @@ -181,11 +193,11 @@ interface types { /// The tuple is a pair of the field key, represented as a string, and /// Value, represented as a list of bytes. /// - /// An error result will be returned if any `field-key` or `field-value` is + /// An error result will be returned if any `field-name` or `field-value` is /// syntactically invalid, or if a field is forbidden. @since(version = 0.2.0) from-list: static func( - entries: list> + entries: list> ) -> result; /// Get all of the values corresponding to a key. If the key is not present @@ -193,42 +205,42 @@ interface types { /// However, if the key is present but empty, this is represented by a list /// with one or more empty field-values present. @since(version = 0.2.0) - get: func(name: field-key) -> list; + get: func(name: field-name) -> list; /// Returns `true` when the key is present in this `fields`. If the key is /// syntactically invalid, `false` is returned. @since(version = 0.2.0) - has: func(name: field-key) -> bool; + has: func(name: field-name) -> bool; /// Set all of the values for a key. Clears any existing values for that /// key, if they have been set. /// /// Fails with `header-error.immutable` if the `fields` are immutable. /// - /// Fails with `header-error.invalid-syntax` if the `field-key` or any of + /// Fails with `header-error.invalid-syntax` if the `field-name` or any of /// the `field-value`s are syntactically invalid. @since(version = 0.2.0) - set: func(name: field-key, value: list) -> result<_, header-error>; + set: func(name: field-name, value: list) -> result<_, header-error>; /// Delete all values for a key. Does nothing if no values for the key /// exist. /// /// Fails with `header-error.immutable` if the `fields` are immutable. /// - /// Fails with `header-error.invalid-syntax` if the `field-key` is + /// Fails with `header-error.invalid-syntax` if the `field-name` is /// syntactically invalid. @since(version = 0.2.0) - delete: func(name: field-key) -> result<_, header-error>; + delete: func(name: field-name) -> result<_, header-error>; /// Append a value for a key. Does not change or delete any existing /// values for that key. /// /// Fails with `header-error.immutable` if the `fields` are immutable. /// - /// Fails with `header-error.invalid-syntax` if the `field-key` or + /// Fails with `header-error.invalid-syntax` if the `field-name` or /// `field-value` are syntactically invalid. @since(version = 0.2.0) - append: func(name: field-key, value: field-value) -> result<_, header-error>; + append: func(name: field-name, value: field-value) -> result<_, header-error>; /// Retrieve the full set of keys and values in the Fields. Like the /// constructor, the list represents each key-value pair. @@ -236,8 +248,11 @@ interface types { /// The outer list represents each key-value pair in the Fields. Keys /// which have multiple values are represented by multiple entries in this /// list with the same key. + /// + /// The keys and values are always returned in the original casing and in + /// the order in which they will be serialized for transport. @since(version = 0.2.0) - entries: func() -> list>; + entries: func() -> list>; /// Make a deep copy of the Fields. Equivalent in behavior to calling the /// `fields` constructor on the return value of `entries`. The resulting From 84a99f45f88df41656621beec5cc0afea68543a0 Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 14 Aug 2024 15:04:06 +0200 Subject: [PATCH 03/10] update to wit-bindgen@0.30.0 --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2d34992..b8f6fd9 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -18,5 +18,5 @@ jobs: ./wit-deps lock --check - uses: WebAssembly/wit-abi-up-to-date@v21 with: - wit-bindgen: '0.28.0' + wit-bindgen: '0.30.0' worlds: 'imports proxy' From 70b456a187fef646c07b8ca71cfa86ca3afb54fc Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 14 Aug 2024 15:06:47 +0200 Subject: [PATCH 04/10] generate `import` docs --- imports.md | 799 +++++++++++++++++++++++++++-------------------------- 1 file changed, 405 insertions(+), 394 deletions(-) diff --git a/imports.md b/imports.md index c4abffb..22d946e 100644 --- a/imports.md +++ b/imports.md @@ -1,4 +1,4 @@ -

    World imports

    +

    World imports

    The wasi:http/imports world imports all the APIs for HTTP proxies. It is intended to be included in other worlds.

      @@ -18,35 +18,35 @@ It is intended to be included in other worlds.

    -

    Import interface wasi:io/poll@0.2.1

    +

    Import interface wasi:io/poll@0.2.1

    A poll API intended to let users wait for I/O events on multiple handles at once.

    Types

    -

    resource pollable

    +

    resource pollable

    pollable represents a single I/O event which may be ready, or not.

    Functions

    -

    [method]pollable.ready: func

    +

    [method]pollable.ready: func

    Return the readiness of a pollable. This function never blocks.

    Returns true when the pollable is ready, and false otherwise.

    Params
    Return values
      -
    • bool
      • +
    • bool
    -

    [method]pollable.block: func

    +

    [method]pollable.block: func

    block returns immediately if the pollable is ready, and otherwise blocks until ready.

    This function is equivalent to calling poll.poll on a list containing only this pollable.

    Params
    -

    poll: func

    +

    poll: func

    Poll for completion on a set of pollables.

    This function takes a list of pollables, which identify I/O sources of interest, and waits until one or more of the events is ready for I/O.

    @@ -65,13 +65,13 @@ the pollables has an error, it is indicated by marking the source as being ready for I/O.

    Params
    Return values
      -
    • list<u32>
      • +
    • list<u32>
    -

    Import interface wasi:clocks/monotonic-clock@0.2.1

    +

    Import interface wasi:clocks/monotonic-clock@0.2.1

    WASI Monotonic Clock is a clock API intended to let users measure elapsed time.

    It is intended to be portable at least between Unix-family platforms and @@ -80,57 +80,57 @@ Windows.

    successive reads of the clock will produce non-decreasing values.

    Types

    -

    type pollable

    +

    type pollable

    pollable

    -#### `type instant` +#### `type instant` `u64`

    An instant in time, in nanoseconds. An instant is relative to an unspecified initial value, and can only be compared to instances from the same monotonic-clock. -

    type duration

    +

    type duration

    u64

    A duration of time, in nanoseconds.

    Functions

    -

    now: func

    +

    now: func

    Read the current value of the clock.

    The clock is monotonic, therefore calling this function repeatedly will produce a sequence of non-decreasing values.

    Return values
    -

    resolution: func

    +

    resolution: func

    Query the resolution of the clock. Returns the duration of time corresponding to a clock tick.

    Return values
    -

    subscribe-instant: func

    +

    subscribe-instant: func

    Create a pollable which will resolve once the specified instant has occurred.

    Params
    Return values
    -

    subscribe-duration: func

    +

    subscribe-duration: func

    Create a pollable that will resolve after the specified duration has elapsed from the time this function is invoked.

    Params
    Return values
    -

    Import interface wasi:clocks/wall-clock@0.2.1

    +

    Import interface wasi:clocks/wall-clock@0.2.1

    WASI Wall Clock is a clock API intended to let users query the current time. The name "wall" makes an analogy to a "clock on the wall", which is not necessarily monotonic as it may be reset.

    @@ -143,16 +143,16 @@ monotonic, making it unsuitable for measuring elapsed time.

    It is intended for reporting the current date and time for humans.

    Types

    -

    record datetime

    +

    record datetime

    A time and date in seconds plus nanoseconds.

    Record Fields
      -
    • seconds: u64
      • -
    • nanoseconds: u32
      • +
    • seconds: u64
      • +
    • nanoseconds: u32

    Functions

    -

    now: func

    +

    now: func

    Read the current value of the clock.

    This clock is not monotonic, therefore calling this function repeatedly will not necessarily produce a sequence of non-decreasing values.

    @@ -162,22 +162,22 @@ also known as Unix Time.The nanoseconds field of the output is always less than 1000000000.

    Return values
    -

    resolution: func

    +

    resolution: func

    Query the resolution of the clock.

    The nanoseconds field of the output is always less than 1000000000.

    Return values
    -

    Import interface wasi:random/random@0.2.1

    +

    Import interface wasi:random/random@0.2.1

    WASI Random is a random data API.

    It is intended to be portable at least between Unix-family platforms and Windows.

    Functions

    -

    get-random-bytes: func

    +

    get-random-bytes: func

    Return len cryptographically-secure random or pseudo-random bytes.

    This function must produce data at least as cryptographically secure and fast as an adequately seeded cryptographically-secure pseudo-random @@ -190,24 +190,24 @@ must omit this function, rather than implementing it with deterministic data.

    Params
      -
    • len: u64
      • +
    • len: u64
    Return values
      -
    • list<u8>
      • +
    • list<u8>
    -

    get-random-u64: func

    +

    get-random-u64: func

    Return a cryptographically-secure random or pseudo-random u64 value.

    This function returns the same type of data as get-random-bytes, represented as a u64.

    Return values
      -
    • u64
      • +
    • u64
    -

    Import interface wasi:io/error@0.2.1

    +

    Import interface wasi:io/error@0.2.1

    Types

    -

    resource error

    +

    resource error

    A resource which represents some error information.

    The only method provided by this resource is to-debug-string, which provides some human-readable information about the error.

    @@ -222,7 +222,7 @@ parameter and returns an option<wasi:filesystem/types/error-code>The set of functions which can "downcast" an error into a more concrete type is open.

    Functions

    -

    [method]error.to-debug-string: func

    +

    [method]error.to-debug-string: func

    Returns a string that is suitable to assist humans in debugging this error.

    WARNING: The returned string should not be consumed mechanically! @@ -231,42 +231,42 @@ details. Parsing this string is a major platform-compatibility hazard.

    Params
    Return values
      -
    • string
      • +
    • string
    -

    Import interface wasi:io/streams@0.2.1

    +

    Import interface wasi:io/streams@0.2.1

    WASI I/O is an I/O abstraction API which is currently focused on providing stream types.

    In the future, the component model is expected to add built-in stream types; when it does, they are expected to subsume this API.

    Types

    -

    type error

    +

    type error

    error

    -#### `type pollable` +#### `type pollable` [`pollable`](#pollable)

    -#### `variant stream-error` +#### `variant stream-error`

    An error for input-stream and output-stream operations.

    Variant Cases
    • -

      last-operation-failed: own<error>

      +

      last-operation-failed: own<error>

      The last operation (a write or flush) failed before completion.

      More information is available in the error payload.

    • -

      closed

      +

      closed

      The stream is closed: no more input will be accepted by the stream. A closed output-stream will return this error on all future operations.

    -

    resource input-stream

    +

    resource input-stream

    An input bytestream.

    input-streams are non-blocking to the extent practical on underlying platforms. I/O operations always return promptly; if fewer bytes are @@ -274,7 +274,7 @@ promptly available than requested, they return the number of bytes promptly available, which could even be zero. To wait for data to be available, use the subscribe function to obtain a pollable which can be polled for using wasi:io/poll.

    -

    resource output-stream

    +

    resource output-stream

    An output bytestream.

    output-streams are non-blocking to the extent practical on underlying platforms. Except where specified otherwise, I/O operations also @@ -286,7 +286,7 @@ polled for using wasi:io/poll.

    progress may result in the data being lost. Before dropping the stream, be sure to fully flush your writes.

    Functions

    -

    [method]input-stream.read: func

    +

    [method]input-stream.read: func

    Perform a non-blocking read from the stream.

    When the source of a read is binary data, the bytes from the source are returned verbatim. When the source of a read is known to the @@ -310,51 +310,51 @@ as a return value by the callee. The callee may return a list of bytes less than len in size while more bytes are available for reading.

    Params
    Return values
    -

    [method]input-stream.blocking-read: func

    +

    [method]input-stream.blocking-read: func

    Read bytes from a stream, after blocking until at least one byte can be read. Except for blocking, behavior is identical to read.

    Params
    Return values
    -

    [method]input-stream.skip: func

    +

    [method]input-stream.skip: func

    Skip bytes from a stream. Returns number of bytes skipped.

    Behaves identical to read, except instead of returning a list of bytes, returns the number of bytes consumed from the stream.

    Params
    Return values
    -

    [method]input-stream.blocking-skip: func

    +

    [method]input-stream.blocking-skip: func

    Skip bytes from a stream, after blocking until at least one byte can be skipped. Except for blocking behavior, identical to skip.

    Params
    Return values
    -

    [method]input-stream.subscribe: func

    +

    [method]input-stream.subscribe: func

    Create a pollable which will resolve once either the specified stream has bytes available to read or the other end of the stream has been closed. @@ -363,13 +363,13 @@ Implementations may trap if the input-streampollables created with this function are dropped.

    Params
    Return values
    -

    [method]output-stream.check-write: func

    +

    [method]output-stream.check-write: func

    Check readiness for writing. This function never blocks.

    Returns the number of bytes permitted for the next call to write, or an error. Calling write with more bytes than this function has @@ -379,13 +379,13 @@ become ready when this function will report at least 1 byte, or an error.

    Params
    Return values
    -

    [method]output-stream.write: func

    +

    [method]output-stream.write: func

    Perform a write. This function never blocks.

    When the destination of a write is binary data, the bytes from contents are written verbatim. When the destination of a write is @@ -398,14 +398,14 @@ length of less than or equal to n. Otherwise, this function will trap.

    the last call to check-write provided a permit.

    Params
    Return values
    -

    [method]output-stream.blocking-write-and-flush: func

    +

    [method]output-stream.blocking-write-and-flush: func

    Perform a write of up to 4096 bytes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

    This is a convenience wrapper around the use of check-write, @@ -429,14 +429,14 @@ let _ = this.check-write(); // eliding error handling

    Params
    Return values
    -

    [method]output-stream.flush: func

    +

    [method]output-stream.flush: func

    Request to flush buffered output. This function never blocks.

    This tells the output-stream that the caller intends any buffered output to be flushed. the output which is expected to be flushed @@ -447,24 +447,24 @@ completed. The subscribe pollable will become ready when the flush has completed and the stream can accept more writes.

    Params
    Return values
    -

    [method]output-stream.blocking-flush: func

    +

    [method]output-stream.blocking-flush: func

    Request to flush buffered output, and block until flush completes and stream is ready for writing again.

    Params
    Return values
    -

    [method]output-stream.subscribe: func

    +

    [method]output-stream.subscribe: func

    Create a pollable which will resolve once the output-stream is ready for more writing, or an error has occurred. When this pollable is ready, check-write will return ok(n) with n>0, or an @@ -475,13 +475,13 @@ Implementations may trap if the output-streampollables created with this function are dropped.

    Params
    Return values
    -

    [method]output-stream.write-zeroes: func

    +

    [method]output-stream.write-zeroes: func

    Write zeroes to a stream.

    This should be used precisely like write with the exact same preconditions (must use check-write first), but instead of @@ -489,14 +489,14 @@ passing a list of bytes, you simply pass the number of zero-bytes that should be written.

    Params
    Return values
    -

    [method]output-stream.blocking-write-zeroes-and-flush: func

    +

    [method]output-stream.blocking-write-zeroes-and-flush: func

    Perform a write of up to 4096 zeroes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

    @@ -520,14 +520,14 @@ let _ = this.check-write(); // eliding error handling
    Params
    Return values
    -

    [method]output-stream.splice: func

    +

    [method]output-stream.splice: func

    Read from one stream and write to another.

    The behavior of splice is equivalent to:

      @@ -542,214 +542,223 @@ let _ = this.check-write(); // eliding error handling than len.

      Params
      Return values
      -

      [method]output-stream.blocking-splice: func

      +

      [method]output-stream.blocking-splice: func

      Read from one stream and write to another, with blocking.

      This is similar to splice, except that it blocks until the output-stream is ready for writing, and the input-stream is ready for reading, before performing the splice.

      Params
      Return values
      -

      Import interface wasi:cli/stdout@0.2.1

      +

      Import interface wasi:cli/stdout@0.2.1

      Types

      -

      type output-stream

      +

      type output-stream

      output-stream

      ----

      Functions

      -

      get-stdout: func

      +

      get-stdout: func

      Return values
      -

      Import interface wasi:cli/stderr@0.2.1

      +

      Import interface wasi:cli/stderr@0.2.1

      Types

      -

      type output-stream

      +

      type output-stream

      output-stream

      ----

      Functions

      -

      get-stderr: func

      +

      get-stderr: func

      Return values
      -

      Import interface wasi:cli/stdin@0.2.1

      +

      Import interface wasi:cli/stdin@0.2.1

      Types

      -

      type input-stream

      +

      type input-stream

      input-stream

      ----

      Functions

      -

      get-stdin: func

      +

      get-stdin: func

      Return values
      -

      Import interface wasi:http/types@0.2.1

      +

      Import interface wasi:http/types@0.2.1

      This interface defines all of the types and methods for implementing HTTP Requests and Responses, both incoming and outgoing, as well as their headers, trailers, and bodies.

      Types

      -

      type duration

      +

      type duration

      duration

      -#### `type input-stream` +#### `type input-stream` [`input-stream`](#input_stream)

      -#### `type output-stream` +#### `type output-stream` [`output-stream`](#output_stream)

      -#### `type io-error` +#### `type io-error` [`error`](#error)

      -#### `type pollable` +#### `type pollable` [`pollable`](#pollable)

      -#### `variant method` +#### `variant method`

      This type corresponds to HTTP standard Methods.

      Variant Cases
        -
      • get
        • -
      • head
        • -
      • post
        • -
      • put
        • -
      • delete
        • -
      • connect
        • -
      • options
        • -
      • trace
        • -
      • patch
        • -
      • other: string
        • -
      -

      variant scheme

      +
    1. get
      2. +
    2. head
      3. +
    3. post
      4. +
    4. put
      5. +
    5. delete
      6. +
    6. connect
      7. +
    7. options
      8. +
    8. trace
      9. +
    9. patch
      10. +
    10. other: string
      11. + +

      variant scheme

      This type corresponds to HTTP standard Related Schemes.

      Variant Cases
        -
      • HTTP
        • -
      • HTTPS
        • -
      • other: string
        • +
      • HTTP
        • +
      • HTTPS
        • +
      • other: string
      -

      record DNS-error-payload

      +

      record DNS-error-payload

      Defines the case payload type for DNS-error above:

      Record Fields
        -
      • rcode: option<string>
        • -
      • info-code: option<u16>
        • +
      • rcode: option<string>
        • +
      • info-code: option<u16>
      -

      record TLS-alert-received-payload

      +

      record TLS-alert-received-payload

      Defines the case payload type for TLS-alert-received above:

      Record Fields
        -
      • alert-id: option<u8>
        • -
      • alert-message: option<string>
        • +
      • alert-id: option<u8>
        • +
      • alert-message: option<string>
      -

      record field-size-payload

      +

      record field-size-payload

      Defines the case payload type for HTTP-response-{header,trailer}-size above:

      Record Fields
        -
      • field-name: option<string>
        • -
      • field-size: option<u32>
        • +
      • field-name: option<string>
        • +
      • field-size: option<u32>
      -

      variant error-code

      +

      variant error-code

      These cases are inspired by the IANA HTTP Proxy Error Types: https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types

      Variant Cases
        -
      • DNS-timeout
        • -
      • DNS-error: DNS-error-payload
        • -
      • destination-not-found
        • -
      • destination-unavailable
        • -
      • destination-IP-prohibited
        • -
      • destination-IP-unroutable
        • -
      • connection-refused
        • -
      • connection-terminated
        • -
      • connection-timeout
        • -
      • connection-read-timeout
        • -
      • connection-write-timeout
        • -
      • connection-limit-reached
        • -
      • TLS-protocol-error
        • -
      • TLS-certificate-error
        • -
      • TLS-alert-received: TLS-alert-received-payload
        • -
      • HTTP-request-denied
        • -
      • HTTP-request-length-required
        • -
      • HTTP-request-body-size: option<u64>
        • -
      • HTTP-request-method-invalid
        • -
      • HTTP-request-URI-invalid
        • -
      • HTTP-request-URI-too-long
        • -
      • HTTP-request-header-section-size: option<u32>
        • -
      • HTTP-request-header-size: option<field-size-payload>
        • -
      • HTTP-request-trailer-section-size: option<u32>
        • -
      • HTTP-request-trailer-size: field-size-payload
        • -
      • HTTP-response-incomplete
        • -
      • HTTP-response-header-section-size: option<u32>
        • -
      • HTTP-response-header-size: field-size-payload
        • -
      • HTTP-response-body-size: option<u64>
        • -
      • HTTP-response-trailer-section-size: option<u32>
        • -
      • HTTP-response-trailer-size: field-size-payload
        • -
      • HTTP-response-transfer-coding: option<string>
        • -
      • HTTP-response-content-coding: option<string>
        • -
      • HTTP-response-timeout
        • -
      • HTTP-upgrade-failed
        • -
      • HTTP-protocol-error
        • -
      • loop-detected
        • -
      • configuration-error
        • -
      • internal-error: option<string>

        This is a catch-all error for anything that doesn't fit cleanly into a +

      • DNS-timeout
        • +
      • DNS-error: DNS-error-payload
        • +
      • destination-not-found
        • +
      • destination-unavailable
        • +
      • destination-IP-prohibited
        • +
      • destination-IP-unroutable
        • +
      • connection-refused
        • +
      • connection-terminated
        • +
      • connection-timeout
        • +
      • connection-read-timeout
        • +
      • connection-write-timeout
        • +
      • connection-limit-reached
        • +
      • TLS-protocol-error
        • +
      • TLS-certificate-error
        • +
      • TLS-alert-received: TLS-alert-received-payload
        • +
      • HTTP-request-denied
        • +
      • HTTP-request-length-required
        • +
      • HTTP-request-body-size: option<u64>
        • +
      • HTTP-request-method-invalid
        • +
      • HTTP-request-URI-invalid
        • +
      • HTTP-request-URI-too-long
        • +
      • HTTP-request-header-section-size: option<u32>
        • +
      • HTTP-request-header-size: option<field-size-payload>
        • +
      • HTTP-request-trailer-section-size: option<u32>
        • +
      • HTTP-request-trailer-size: field-size-payload
        • +
      • HTTP-response-incomplete
        • +
      • HTTP-response-header-section-size: option<u32>
        • +
      • HTTP-response-header-size: field-size-payload
        • +
      • HTTP-response-body-size: option<u64>
        • +
      • HTTP-response-trailer-section-size: option<u32>
        • +
      • HTTP-response-trailer-size: field-size-payload
        • +
      • HTTP-response-transfer-coding: option<string>
        • +
      • HTTP-response-content-coding: option<string>
        • +
      • HTTP-response-timeout
        • +
      • HTTP-upgrade-failed
        • +
      • HTTP-protocol-error
        • +
      • loop-detected
        • +
      • configuration-error
        • +
      • internal-error: option<string>

        This is a catch-all error for anything that doesn't fit cleanly into a more specific case. 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.

      -

      variant header-error

      +

      variant header-error

      This type enumerates the different kinds of errors that may occur when setting or appending to a fields resource.

      Variant Cases
      • -

        invalid-syntax

        -

        This error indicates that a `field-key` or `field-value` was +

        invalid-syntax

        +

        This error indicates that a `field-name` or `field-value` was syntactically invalid when used with an operation that sets headers in a `fields`.

      • -

        forbidden

        -

        This error indicates that a forbidden `field-key` was used when trying +

        forbidden

        +

        This error indicates that a forbidden `field-name` was used when trying to set a header in a `fields`.

      • -

        immutable

        +

        immutable

        This error indicates that the operation on the `fields` was not permitted because the fields are immutable.

      -

      type field-key

      +

      type field-key

      string

      Field keys are always strings. -

      type field-value

      +

      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.

      +

      type field-name

      +

      field-key

      +

      Field names are always strings. +

      Field keys should always be treated as case insensitive by the fields +resource for the purposes of equality checking.

      +

      type field-value

      field-value

      Field values should always be ASCII strings. However, in reality, HTTP implementations often have to interpret malformed values, so they are provided as a list of bytes. -

      resource fields

      +

      resource fields

      This following block defines the fields resource which corresponds to HTTP standard Fields. Fields are a common representation used for both Headers and Trailers.

      @@ -759,33 +768,33 @@ resource given by other means (including, but not limited to, incoming-request.headers, outgoing-request.headers) might be be immutable. In an immutable fields, the set, append, and delete operations will fail with header-error.immutable.

      -

      type headers

      +

      type headers

      fields

      Headers is an alias for Fields. -

      type trailers

      +

      type trailers

      fields

      Trailers is an alias for Fields. -

      resource incoming-request

      +

      resource incoming-request

      Represents an incoming HTTP Request.

      -

      resource outgoing-request

      +

      resource outgoing-request

      Represents an outgoing HTTP Request.

      -

      resource request-options

      +

      resource request-options

      Parameters for making an HTTP Request. Each of these parameters is currently an optional timeout applicable to the transport layer of the HTTP protocol.

      These timeouts are separate from any the user may use to bound a blocking call to wasi:io/poll.poll.

      -

      resource response-outparam

      +

      resource response-outparam

      Represents the ability to send an HTTP Response.

      This resource is used by the wasi:http/incoming-handler interface to allow a Response to be sent corresponding to the Request provided as the other argument to incoming-handler.handle.

      -

      type status-code

      +

      type status-code

      u16

      This type corresponds to the HTTP standard Status Code. -

      resource incoming-response

      +

      resource incoming-response

      Represents an incoming HTTP Response.

      -

      resource incoming-body

      +

      resource incoming-body

      Represents an incoming HTTP Request or Response's Body.

      A body has both its contents - a stream of bytes - and a (possibly empty) set of trailers, indicating that the full contents of the @@ -793,14 +802,14 @@ body have been received. This resource represents the contents as an input-stream and the delivery of trailers as a future-trailers, and ensures that the user of this interface may only be consuming either the body contents or waiting on trailers at any given time.

      -

      resource future-trailers

      +

      resource future-trailers

      Represents a future which may eventually return trailers, or an error.

      In the case that the incoming HTTP Request or Response did not have any trailers, this future will resolve to the empty set of trailers once the complete Request or Response body has been received.

      -

      resource outgoing-response

      +

      resource outgoing-response

      Represents an outgoing HTTP Response.

      -

      resource outgoing-body

      +

      resource outgoing-body

      Represents an outgoing HTTP Request or Response's Body.

      A body has both its contents - a stream of bytes - and a (possibly empty) set of trailers, inducating the full contents of the body @@ -815,13 +824,13 @@ and that an error has occurred. The implementation should propagate this error to the HTTP protocol by whatever means it has available, including: corrupting the body on the wire, aborting the associated Request, or sending a late status code for the Response.

      -

      resource future-incoming-response

      +

      resource future-incoming-response

      Represents a future which may eventually return an incoming HTTP Response, or an error.

      This resource is returned by the wasi:http/outgoing-handler interface to provide the HTTP Response corresponding to the sent Request.

      Functions

      -

      http-error-code: func

      +

      http-error-code: func

      Attempts to extract a http-related error from the wasi:io error provided.

      Stream operations which return @@ -833,20 +842,20 @@ if there's http-related information about the error to return.

      http-related errors.

      Params
      Return values
      -

      [constructor]fields: func

      +

      [constructor]fields: func

      Construct an empty HTTP Fields.

      The resulting fields is mutable.

      Return values
      -

      [static]fields.from-list: func

      +

      [static]fields.from-list: func

      Construct an HTTP Fields.

      The resulting fields is mutable.

      The list represents each key-value pair in the Fields. Keys @@ -854,156 +863,158 @@ which have multiple values are represented by multiple entries in this list with the same key.

      The tuple is a pair of the field key, represented as a string, and Value, represented as a list of bytes.

      -

      An error result will be returned if any field-key or field-value is +

      An error result will be returned if any field-name or field-value is syntactically invalid, or if a field is forbidden.

      Params
      Return values
      -

      [method]fields.get: func

      +

      [method]fields.get: func

      Get all of the values corresponding to a key. If the key is not present in this fields or is syntactically invalid, an empty list is returned. However, if the key is present but empty, this is represented by a list with one or more empty field-values present.

      Params
      Return values
      -

      [method]fields.has: func

      +

      [method]fields.has: func

      Returns true when the key is present in this fields. If the key is syntactically invalid, false is returned.

      Params
      Return values
        -
      • bool
        • +
      • bool
      -

      [method]fields.set: func

      +

      [method]fields.set: func

      Set all of the values for a key. Clears any existing values for that key, if they have been set.

      Fails with header-error.immutable if the fields are immutable.

      -

      Fails with header-error.invalid-syntax if the field-key or any of +

      Fails with header-error.invalid-syntax if the field-name or any of the field-values are syntactically invalid.

      Params
      Return values
      -

      [method]fields.delete: func

      +

      [method]fields.delete: func

      Delete all values for a key. Does nothing if no values for the key exist.

      Fails with header-error.immutable if the fields are immutable.

      -

      Fails with header-error.invalid-syntax if the field-key is +

      Fails with header-error.invalid-syntax if the field-name is syntactically invalid.

      Params
      Return values
      -

      [method]fields.append: func

      +

      [method]fields.append: func

      Append a value for a key. Does not change or delete any existing values for that key.

      Fails with header-error.immutable if the fields are immutable.

      -

      Fails with header-error.invalid-syntax if the field-key or +

      Fails with header-error.invalid-syntax if the field-name or field-value are syntactically invalid.

      Params
      Return values
      -

      [method]fields.entries: func

      +

      [method]fields.entries: func

      Retrieve the full set of keys and values in the Fields. Like the constructor, the list represents each key-value pair.

      The outer list represents each key-value pair in the Fields. Keys which have multiple values are represented by multiple entries in this list with the same key.

      +

      The keys and values are always returned in the original casing and in +the order in which they will be serialized for transport.

      Params
      Return values
      -

      [method]fields.clone: func

      +

      [method]fields.clone: func

      Make a deep copy of the Fields. Equivalent in behavior to calling the fields constructor on the return value of entries. The resulting fields is mutable.

      Params
      Return values
      -

      [method]incoming-request.method: func

      +

      [method]incoming-request.method: func

      Returns the method of the incoming request.

      Params
      Return values
      -

      [method]incoming-request.path-with-query: func

      +

      [method]incoming-request.path-with-query: func

      Returns the path with query parameters from the request, as a string.

      Params
      Return values
        -
      • option<string>
        • +
      • option<string>
      -

      [method]incoming-request.scheme: func

      +

      [method]incoming-request.scheme: func

      Returns the protocol scheme from the request.

      Params
      Return values
      -

      [method]incoming-request.authority: func

      +

      [method]incoming-request.authority: func

      Returns the authority of the Request's target URI, if present.

      Params
      Return values
        -
      • option<string>
        • +
      • option<string>
      -

      [method]incoming-request.headers: func

      +

      [method]incoming-request.headers: func

      Get the headers associated with the request.

      The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

      @@ -1012,24 +1023,24 @@ the parent incoming-request is drop incoming-request before all children are dropped will trap.

      Params
      Return values
      -

      [method]incoming-request.consume: func

      +

      [method]incoming-request.consume: func

      Gives the incoming-body associated with this request. Will only return success at most once, and subsequent calls will return error.

      Params
      Return values
      -

      [constructor]outgoing-request: func

      +

      [constructor]outgoing-request: func

      Construct a new outgoing-request with a default method of GET, and none values for path-with-query, scheme, and authority.

        @@ -1042,13 +1053,13 @@ It is the obligation of the outgoing-handler.handle implementation to reject invalid constructions of outgoing-request.

        Params
        Return values
        -

        [method]outgoing-request.body: func

        +

        [method]outgoing-request.body: func

        Returns the resource corresponding to the outgoing Body for this Request.

        Returns success on the first call: the outgoing-body resource for @@ -1056,109 +1067,109 @@ this outgoing-request can be retrie calls will return error.

        Params
        Return values
        -

        [method]outgoing-request.method: func

        +

        [method]outgoing-request.method: func

        Get the Method for the Request.

        Params
        Return values
        -

        [method]outgoing-request.set-method: func

        +

        [method]outgoing-request.set-method: func

        Set the Method for the Request. Fails if the string present in a method.other argument is not a syntactically valid method.

        Params
        Return values
          -
        • result
          • +
        • result
        -

        [method]outgoing-request.path-with-query: func

        +

        [method]outgoing-request.path-with-query: func

        Get the combination of the HTTP Path and Query for the Request. When none, this represents an empty Path and empty Query.

        Params
        Return values
          -
        • option<string>
          • +
        • option<string>
        -

        [method]outgoing-request.set-path-with-query: func

        +

        [method]outgoing-request.set-path-with-query: func

        Set the combination of the HTTP Path and Query for the Request. When none, this represents an empty Path and empty Query. Fails is the string given is not a syntactically valid path and query uri component.

        Params
        Return values
          -
        • result
          • +
        • result
        -

        [method]outgoing-request.scheme: func

        +

        [method]outgoing-request.scheme: func

        Get the HTTP Related Scheme for the Request. When none, the implementation may choose an appropriate default scheme.

        Params
        Return values
        -

        [method]outgoing-request.set-scheme: func

        +

        [method]outgoing-request.set-scheme: func

        Set the HTTP Related Scheme for the Request. When none, the implementation may choose an appropriate default scheme. Fails if the string given is not a syntactically valid uri scheme.

        Params
        Return values
          -
        • result
          • +
        • result
        -

        [method]outgoing-request.authority: func

        +

        [method]outgoing-request.authority: func

        Get the authority of the Request's target URI. A value of none may be used with Related Schemes which do not require an authority. The HTTP and HTTPS schemes always require an authority.

        Params
        Return values
          -
        • option<string>
          • +
        • option<string>
        -

        [method]outgoing-request.set-authority: func

        +

        [method]outgoing-request.set-authority: func

        Set the authority of the Request's target URI. A value of none may be used with Related Schemes which do not require an authority. The HTTP and HTTPS schemes always require an authority. Fails if the string given is not a syntactically valid URI authority.

        Params
        Return values
          -
        • result
          • +
        • result
        -

        [method]outgoing-request.headers: func

        +

        [method]outgoing-request.headers: func

        Get the headers associated with the Request.

        The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

        @@ -1167,87 +1178,87 @@ not a syntactically valid URI authority.

        another component by e.g. outgoing-handler.handle.

        Params
        Return values
        -

        [constructor]request-options: func

        +

        [constructor]request-options: func

        Construct a default request-options value.

        Return values
        -

        [method]request-options.connect-timeout: func

        +

        [method]request-options.connect-timeout: func

        The timeout for the initial connect to the HTTP Server.

        Params
        Return values
        -

        [method]request-options.set-connect-timeout: func

        +

        [method]request-options.set-connect-timeout: func

        Set the timeout for the initial connect to the HTTP Server. An error return value indicates that this timeout is not supported.

        Params
        Return values
          -
        • result
          • +
        • result
        -

        [method]request-options.first-byte-timeout: func

        +

        [method]request-options.first-byte-timeout: func

        The timeout for receiving the first byte of the Response body.

        Params
        Return values
        -

        [method]request-options.set-first-byte-timeout: func

        +

        [method]request-options.set-first-byte-timeout: func

        Set the timeout for receiving the first byte of the Response body. An error return value indicates that this timeout is not supported.

        Params
        Return values
          -
        • result
          • +
        • result
        -

        [method]request-options.between-bytes-timeout: func

        +

        [method]request-options.between-bytes-timeout: func

        The timeout for receiving subsequent chunks of bytes in the Response body stream.

        Params
        Return values
        -

        [method]request-options.set-between-bytes-timeout: func

        +

        [method]request-options.set-between-bytes-timeout: func

        Set the timeout for receiving subsequent chunks of bytes in the Response body stream. An error return value indicates that this timeout is not supported.

        Params
        Return values
          -
        • result
          • +
        • result
        -

        [static]response-outparam.set: func

        +

        [static]response-outparam.set: func

        Set the value of the response-outparam to either send a response, or indicate an error.

        This method consumes the response-outparam to ensure that it is @@ -1257,20 +1268,20 @@ will respond with an error.

        implementation determine how to respond with an HTTP error response.

        Params
        -

        [method]incoming-response.status: func

        +

        [method]incoming-response.status: func

        Returns the status code from the incoming response.

        Params
        Return values
        -

        [method]incoming-response.headers: func

        +

        [method]incoming-response.headers: func

        Returns the headers from the incoming response.

        The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

        @@ -1278,24 +1289,24 @@ implementation determine how to respond with an HTTP error response.

        incoming-response is dropped.

        Params
        Return values
        -

        [method]incoming-response.consume: func

        +

        [method]incoming-response.consume: func

        Returns the incoming body. May be called at most once. Returns error if called additional times.

        Params
        Return values
        -

        [method]incoming-body.stream: func

        +

        [method]incoming-body.stream: func

        Returns the contents of the body, as a stream of bytes.

        Returns success on first call: the stream representing the contents can be retrieved at most once. Subsequent calls will return error.

        @@ -1310,36 +1321,36 @@ and for that backpressure to not inhibit delivery of the trailers if the user does not read the entire body.

        Params
        Return values
        -

        [static]incoming-body.finish: func

        +

        [static]incoming-body.finish: func

        Takes ownership of incoming-body, and returns a future-trailers. This function will trap if the input-stream child is still alive.

        Params
        Return values
        -

        [method]future-trailers.subscribe: func

        +

        [method]future-trailers.subscribe: func

        Returns a pollable which becomes ready when either the trailers have been received, or an error has occurred. When this pollable is ready, the get method will return some.

        Params
        Return values
        -

        [method]future-trailers.get: func

        +

        [method]future-trailers.get: func

        Returns the contents of the trailers, or an error which occurred, once the future is ready.

        The outer option represents future readiness. Users can wait on this @@ -1357,13 +1368,13 @@ resource is immutable, and a child. Use of the set, appendfuture-trailers is dropped.

        Params
        Return values
        -

        [constructor]outgoing-response: func

        +

        [constructor]outgoing-response: func

        Construct an outgoing-response, with a default status-code of 200. If a different status-code is needed, it must be set via the set-status-code method.

        @@ -1372,35 +1383,35 @@ If a different status-code is needed, it
      Params
      Return values
      -

      [method]outgoing-response.status-code: func

      +

      [method]outgoing-response.status-code: func

      Get the HTTP Status Code for the Response.

      Params
      Return values
      -

      [method]outgoing-response.set-status-code: func

      +

      [method]outgoing-response.set-status-code: func

      Set the HTTP Status Code for the Response. Fails if the status-code given is not a valid http status code.

      Params
      Return values
        -
      • result
        • +
      • result
      -

      [method]outgoing-response.headers: func

      +

      [method]outgoing-response.headers: func

      Get the headers associated with the Request.

      The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

      @@ -1409,26 +1420,26 @@ given is not a valid http status code.

      another component by e.g. outgoing-handler.handle.

      Params
      Return values
      -

      [method]outgoing-response.body: func

      +

      [method]outgoing-response.body: func

      Returns the resource corresponding to the outgoing Body for this Response.

      Returns success on the first call: the outgoing-body resource for this outgoing-response can be retrieved at most once. Subsequent calls will return error.

      Params
      Return values
      -

      [method]outgoing-body.write: func

      +

      [method]outgoing-body.write: func

      Returns a stream for writing the body contents.

      The returned output-stream is a child resource: it must be dropped before the parent outgoing-body resource is dropped (or finished), @@ -1438,13 +1449,13 @@ this outgoing-body may be retrieved at will return error.

      Params
      Return values
      -

      [static]outgoing-body.finish: func

      +

      [static]outgoing-body.finish: func

      Finalize an outgoing body, optionally providing trailers. This must be called to signal that the response is complete. If the outgoing-body is dropped without calling outgoing-body.finalize, the implementation @@ -1455,26 +1466,26 @@ to the body (via write) does not match the value given in the Content-Length.

      Params
      Return values
      -

      [method]future-incoming-response.subscribe: func

      +

      [method]future-incoming-response.subscribe: func

      Returns a pollable which becomes ready when either the Response has been received, or an error has occurred. When this pollable is ready, the get method will return some.

      Params
      Return values
      -

      [method]future-incoming-response.get: func

      +

      [method]future-incoming-response.get: func

      Returns the incoming HTTP Response, or an error, once one is ready.

      The outer option represents future readiness. Users can wait on this option to become some using the subscribe method.

      @@ -1488,32 +1499,32 @@ but those will be reported by the incoming-bodyoutput-stream child.

      Params
      Return values
      -

      Import interface wasi:http/outgoing-handler@0.2.1

      +

      Import interface wasi:http/outgoing-handler@0.2.1

      This interface defines a handler of outgoing HTTP Requests. It should be imported by components which wish to make HTTP Requests.

      Types

      -

      type outgoing-request

      +

      type outgoing-request

      outgoing-request

      -#### `type request-options` +#### `type request-options` [`request-options`](#request_options)

      -#### `type future-incoming-response` +#### `type future-incoming-response` [`future-incoming-response`](#future_incoming_response)

      -#### `type error-code` +#### `type error-code` [`error-code`](#error_code)

      ----

      Functions

      -

      handle: func

      +

      handle: func

      This function is invoked with an outgoing HTTP Request, and it returns a resource future-incoming-response which represents an HTTP Response which may arrive in the future.

      @@ -1524,10 +1535,10 @@ or not allowed to be made. Otherwise, protocol errors are reported through the future-incoming-response.

      Params
      Return values
      From 6b00fa4c80a94f0a67940a9651b2bd141a6c60d9 Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 14 Aug 2024 15:12:18 +0200 Subject: [PATCH 05/10] pin `wasm-tools` version in CI --- .github/workflows/main.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index b8f6fd9..3bfc2ee 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -18,5 +18,6 @@ jobs: ./wit-deps lock --check - uses: WebAssembly/wit-abi-up-to-date@v21 with: + wasm-tools: '1.215.0' wit-bindgen: '0.30.0' worlds: 'imports proxy' From 44138f8862237e747b2f579bcd51586ae7be1f97 Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 21 Aug 2024 16:36:16 +0200 Subject: [PATCH 06/10] bump `wit-abi-up-to-date` --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 3bfc2ee..e5ad565 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -16,7 +16,7 @@ jobs: curl -Lo 'wit-deps' https://github.com/bytecodealliance/wit-deps/releases/download/v0.3.2/wit-deps-x86_64-unknown-linux-musl chmod +x ./wit-deps ./wit-deps lock --check - - uses: WebAssembly/wit-abi-up-to-date@v21 + - uses: WebAssembly/wit-abi-up-to-date@v22 with: wasm-tools: '1.215.0' wit-bindgen: '0.30.0' From d155be54d0e678814f905bc7d3a870f02e55a6b5 Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 21 Aug 2024 16:42:04 +0200 Subject: [PATCH 07/10] Replace all references to `field-key` in docs Co-Authored-By: Luke Wagner --- wit-0.3.0-draft/types.wit | 40 +++++++++++++++++++-------------------- wit/types.wit | 34 ++++++++++++++++----------------- 2 files changed, 37 insertions(+), 37 deletions(-) diff --git a/wit-0.3.0-draft/types.wit b/wit-0.3.0-draft/types.wit index e562d8d..1f3c688 100644 --- a/wit-0.3.0-draft/types.wit +++ b/wit-0.3.0-draft/types.wit @@ -134,7 +134,7 @@ interface types { /// Field names are always strings. /// - /// Field keys should always be treated as case insensitive by the `fields` + /// Field names should always be treated as case insensitive by the `fields` /// resource for the purposes of equality checking. type field-name = string; @@ -168,12 +168,12 @@ interface types { /// /// The resulting `fields` is mutable. /// - /// The list represents each key-value pair in the Fields. Keys + /// The list represents each name-value pair in the Fields. Names /// which have multiple values are represented by multiple entries in this - /// list with the same key. + /// list with the same name. /// - /// The tuple is a pair of the field key, represented as a string, and - /// Value, represented as a list of bytes. In a valid Fields, all keys + /// The tuple is a pair of the field name, represented as a string, and + /// Value, represented as a list of bytes. In a valid Fields, all names /// and values are valid UTF-8 strings. However, values are not always /// well-formed, so they are represented as a raw list of bytes. /// @@ -183,50 +183,50 @@ interface types { entries: list> ) -> result; - /// Get all of the values corresponding to a key. If the key is not present - /// in this `fields`, an empty list is returned. However, if the key is + /// Get all of the values corresponding to a name. If the name is not present + /// in this `fields`, an empty list is returned. However, if the name is /// present but empty, this is represented by a list with one or more /// empty field-values present. get: func(name: field-name) -> list; - /// Returns `true` when the key is present in this `fields`. If the key is + /// Returns `true` when the name is present in this `fields`. If the name is /// syntactically invalid, `false` is returned. has: func(name: field-name) -> bool; - /// Set all of the values for a key. Clears any existing values for that - /// key, if they have been set. + /// Set all of the values for a name. Clears any existing values for that + /// name, if they have been set. /// /// Fails with `header-error.immutable` if the `fields` are immutable. set: func(name: field-name, value: list) -> result<_, header-error>; - /// Delete all values for a key. Does nothing if no values for the key + /// Delete all values for a name. Does nothing if no values for the name /// exist. /// /// Fails with `header-error.immutable` if the `fields` are immutable. delete: func(name: field-name) -> result<_, header-error>; - /// Delete all values for a key. Does nothing if no values for the key + /// Delete all values for a name. Does nothing if no values for the name /// exist. /// - /// Returns all values previously corresponding to the key, if any. + /// Returns all values previously corresponding to the name, if any. /// /// Fails with `header-error.immutable` if the `fields` are immutable. get-and-delete: func(name: field-name) -> result, header-error>; - /// Append a value for a key. Does not change or delete any existing - /// values for that key. + /// Append a value for a name. Does not change or delete any existing + /// values for that name. /// /// Fails with `header-error.immutable` if the `fields` are immutable. append: func(name: field-name, value: field-value) -> result<_, header-error>; - /// Retrieve the full set of keys and values in the Fields. Like the - /// constructor, the list represents each key-value pair. + /// Retrieve the full set of names and values in the Fields. Like the + /// constructor, the list represents each name-value pair. /// - /// The outer list represents each key-value pair in the Fields. Keys + /// The outer list represents each name-value pair in the Fields. Names /// which have multiple values are represented by multiple entries in this - /// list with the same key. + /// list with the same name. /// - /// The keys and values are always returned in the original casing and in + /// The names and values are always returned in the original casing and in /// the order in which they will be serialized for transport. entries: func() -> list>; diff --git a/wit/types.wit b/wit/types.wit index 5836a9c..002bed9 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -140,7 +140,7 @@ interface types { /// Field names are always strings. /// - /// Field keys should always be treated as case insensitive by the `fields` + /// Field names should always be treated as case insensitive by the `fields` /// resource for the purposes of equality checking. @since(version = 0.2.1) type field-name = field-key; @@ -186,11 +186,11 @@ interface types { /// /// The resulting `fields` is mutable. /// - /// The list represents each key-value pair in the Fields. Keys + /// The list represents each name-value pair in the Fields. Names /// which have multiple values are represented by multiple entries in this - /// list with the same key. + /// list with the same name. /// - /// The tuple is a pair of the field key, represented as a string, and + /// The tuple is a pair of the field name, represented as a string, and /// Value, represented as a list of bytes. /// /// An error result will be returned if any `field-name` or `field-value` is @@ -200,20 +200,20 @@ interface types { entries: list> ) -> result; - /// Get all of the values corresponding to a key. If the key is not present + /// Get all of the values corresponding to a name. If the name is not present /// in this `fields` or is syntactically invalid, an empty list is returned. - /// However, if the key is present but empty, this is represented by a list + /// However, if the name is present but empty, this is represented by a list /// with one or more empty field-values present. @since(version = 0.2.0) get: func(name: field-name) -> list; - /// Returns `true` when the key is present in this `fields`. If the key is + /// Returns `true` when the name is present in this `fields`. If the name is /// syntactically invalid, `false` is returned. @since(version = 0.2.0) has: func(name: field-name) -> bool; - /// Set all of the values for a key. Clears any existing values for that - /// key, if they have been set. + /// Set all of the values for a name. Clears any existing values for that + /// name, if they have been set. /// /// Fails with `header-error.immutable` if the `fields` are immutable. /// @@ -222,7 +222,7 @@ interface types { @since(version = 0.2.0) set: func(name: field-name, value: list) -> result<_, header-error>; - /// Delete all values for a key. Does nothing if no values for the key + /// Delete all values for a name. Does nothing if no values for the name /// exist. /// /// Fails with `header-error.immutable` if the `fields` are immutable. @@ -232,8 +232,8 @@ interface types { @since(version = 0.2.0) delete: func(name: field-name) -> result<_, header-error>; - /// Append a value for a key. Does not change or delete any existing - /// values for that key. + /// Append a value for a name. Does not change or delete any existing + /// values for that name. /// /// Fails with `header-error.immutable` if the `fields` are immutable. /// @@ -242,14 +242,14 @@ interface types { @since(version = 0.2.0) append: func(name: field-name, value: field-value) -> result<_, header-error>; - /// Retrieve the full set of keys and values in the Fields. Like the - /// constructor, the list represents each key-value pair. + /// Retrieve the full set of names and values in the Fields. Like the + /// constructor, the list represents each name-value pair. /// - /// The outer list represents each key-value pair in the Fields. Keys + /// The outer list represents each name-value pair in the Fields. Names /// which have multiple values are represented by multiple entries in this - /// list with the same key. + /// list with the same name. /// - /// The keys and values are always returned in the original casing and in + /// The names and values are always returned in the original casing and in /// the order in which they will be serialized for transport. @since(version = 0.2.0) entries: func() -> list>; From c170ea06538b5a17a390caaaa27cb0803448c86f Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 21 Aug 2024 16:44:27 +0200 Subject: [PATCH 08/10] Fix doc format issue Co-Authored-By: Luke Wagner --- wit-0.3.0-draft/types.wit | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/wit-0.3.0-draft/types.wit b/wit-0.3.0-draft/types.wit index 1f3c688..f702c15 100644 --- a/wit-0.3.0-draft/types.wit +++ b/wit-0.3.0-draft/types.wit @@ -154,7 +154,8 @@ interface types { /// `set`, `append`, and `delete` operations will fail with /// `header-error.immutable`. /// - /// A `fields` resource should store `field-name`s and `field-value`s in their /// original casing used to construct or mutate the `fields` resource. The `fields` + /// A `fields` resource should store `field-name`s and `field-value`s in their + /// 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. resource fields { From 45b4a62e0b8e37ea4565ca418fa30c2f04396d14 Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 21 Aug 2024 16:46:16 +0200 Subject: [PATCH 09/10] re-generate docs Co-Authored-By: Luke Wagner --- imports.md | 34 +++++++++++++++++----------------- proxy.md | 34 +++++++++++++++++----------------- 2 files changed, 34 insertions(+), 34 deletions(-) diff --git a/imports.md b/imports.md index 22d946e..6a3caf1 100644 --- a/imports.md +++ b/imports.md @@ -751,7 +751,7 @@ resource for the purposes of equality checking.

      type field-name

      field-key

      Field names are always strings. -

      Field keys should always be treated as case insensitive by the fields +

      Field names should always be treated as case insensitive by the fields resource for the purposes of equality checking.

      type field-value

      field-value

      @@ -858,10 +858,10 @@ http-related errors.

      [static]fields.from-list: func

      Construct an HTTP Fields.

      The resulting fields is mutable.

      -

      The list represents each key-value pair in the Fields. Keys +

      The list represents each name-value pair in the Fields. Names which have multiple values are represented by multiple entries in this -list with the same key.

      -

      The tuple is a pair of the field key, represented as a string, and +list with the same name.

      +

      The tuple is a pair of the field name, represented as a string, and Value, represented as a list of bytes.

      An error result will be returned if any field-name or field-value is syntactically invalid, or if a field is forbidden.

      @@ -874,9 +874,9 @@ syntactically invalid, or if a field is forbidden.

    11. result<own<fields>, header-error>

      12. [method]fields.get: func

      -

      Get all of the values corresponding to a key. If the key is not present +

      Get all of the values corresponding to a name. If the name is not present in this fields or is syntactically invalid, an empty list is returned. -However, if the key is present but empty, this is represented by a list +However, if the name is present but empty, this is represented by a list with one or more empty field-values present.

      Params
        @@ -888,7 +888,7 @@ with one or more empty field-values present.

      • list<field-value>

      [method]fields.has: func

      -

      Returns true when the key is present in this fields. If the key is +

      Returns true when the name is present in this fields. If the name is syntactically invalid, false is returned.

      Params
        @@ -900,8 +900,8 @@ syntactically invalid, false is returned.

      • bool

      [method]fields.set: func

      -

      Set all of the values for a key. Clears any existing values for that -key, if they have been set.

      +

      Set all of the values for a name. Clears any existing values for that +name, if they have been set.

      Fails with header-error.immutable if the fields are immutable.

      Fails with header-error.invalid-syntax if the field-name or any of the field-values are syntactically invalid.

      @@ -916,7 +916,7 @@ the field-values are syntactically inval
    12. result<_, header-error>

      13. [method]fields.delete: func

      -

      Delete all values for a key. Does nothing if no values for the key +

      Delete all values for a name. Does nothing if no values for the name exist.

      Fails with header-error.immutable if the fields are immutable.

      Fails with header-error.invalid-syntax if the field-name is @@ -931,8 +931,8 @@ syntactically invalid.

    13. result<_, header-error>

      14. [method]fields.append: func

      -

      Append a value for a key. Does not change or delete any existing -values for that key.

      +

      Append a value for a name. Does not change or delete any existing +values for that name.

      Fails with header-error.immutable if the fields are immutable.

      Fails with header-error.invalid-syntax if the field-name or field-value are syntactically invalid.

      @@ -947,12 +947,12 @@ values for that key.

    14. result<_, header-error>

      15. [method]fields.entries: func

      -

      Retrieve the full set of keys and values in the Fields. Like the -constructor, the list represents each key-value pair.

      -

      The outer list represents each key-value pair in the Fields. Keys +

      Retrieve the full set of names and values in the Fields. Like the +constructor, the list represents each name-value pair.

      +

      The outer list represents each name-value pair in the Fields. Names which have multiple values are represented by multiple entries in this -list with the same key.

      -

      The keys and values are always returned in the original casing and in +list with the same name.

      +

      The names and values are always returned in the original casing and in the order in which they will be serialized for transport.

      Params
        diff --git a/proxy.md b/proxy.md index f019fb5..b0f72e2 100644 --- a/proxy.md +++ b/proxy.md @@ -645,7 +645,7 @@ resource for the purposes of equality checking.

        type field-name

        field-key

        Field names are always strings. -

        Field keys should always be treated as case insensitive by the fields +

        Field names should always be treated as case insensitive by the fields resource for the purposes of equality checking.

        type field-value

        field-value

        @@ -752,10 +752,10 @@ http-related errors.

        [static]fields.from-list: func

        Construct an HTTP Fields.

        The resulting fields is mutable.

        -

        The list represents each key-value pair in the Fields. Keys +

        The list represents each name-value pair in the Fields. Names which have multiple values are represented by multiple entries in this -list with the same key.

        -

        The tuple is a pair of the field key, represented as a string, and +list with the same name.

        +

        The tuple is a pair of the field name, represented as a string, and Value, represented as a list of bytes.

        An error result will be returned if any field-name or field-value is syntactically invalid, or if a field is forbidden.

        @@ -768,9 +768,9 @@ syntactically invalid, or if a field is forbidden.

      • result<own<fields>, header-error>

      [method]fields.get: func

      -

      Get all of the values corresponding to a key. If the key is not present +

      Get all of the values corresponding to a name. If the name is not present in this fields or is syntactically invalid, an empty list is returned. -However, if the key is present but empty, this is represented by a list +However, if the name is present but empty, this is represented by a list with one or more empty field-values present.

      Params
        @@ -782,7 +782,7 @@ with one or more empty field-values present.

      • list<field-value>

      [method]fields.has: func

      -

      Returns true when the key is present in this fields. If the key is +

      Returns true when the name is present in this fields. If the name is syntactically invalid, false is returned.

      Params
        @@ -794,8 +794,8 @@ syntactically invalid, false is returned.

      • bool

      [method]fields.set: func

      -

      Set all of the values for a key. Clears any existing values for that -key, if they have been set.

      +

      Set all of the values for a name. Clears any existing values for that +name, if they have been set.

      Fails with header-error.immutable if the fields are immutable.

      Fails with header-error.invalid-syntax if the field-name or any of the field-values are syntactically invalid.

      @@ -810,7 +810,7 @@ the field-values are syntactically inval
    15. result<_, header-error>

      16. [method]fields.delete: func

      -

      Delete all values for a key. Does nothing if no values for the key +

      Delete all values for a name. Does nothing if no values for the name exist.

      Fails with header-error.immutable if the fields are immutable.

      Fails with header-error.invalid-syntax if the field-name is @@ -825,8 +825,8 @@ syntactically invalid.

    16. result<_, header-error>

      17. [method]fields.append: func

      -

      Append a value for a key. Does not change or delete any existing -values for that key.

      +

      Append a value for a name. Does not change or delete any existing +values for that name.

      Fails with header-error.immutable if the fields are immutable.

      Fails with header-error.invalid-syntax if the field-name or field-value are syntactically invalid.

      @@ -841,12 +841,12 @@ values for that key.

    17. result<_, header-error>

      18. [method]fields.entries: func

      -

      Retrieve the full set of keys and values in the Fields. Like the -constructor, the list represents each key-value pair.

      -

      The outer list represents each key-value pair in the Fields. Keys +

      Retrieve the full set of names and values in the Fields. Like the +constructor, the list represents each name-value pair.

      +

      The outer list represents each name-value pair in the Fields. Names which have multiple values are represented by multiple entries in this -list with the same key.

      -

      The keys and values are always returned in the original casing and in +list with the same name.

      +

      The names and values are always returned in the original casing and in the order in which they will be serialized for transport.

      Params
        From 60fc7b9920f7dedbaaec79d2ebd415470d9d83a2 Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 21 Aug 2024 16:53:52 +0200 Subject: [PATCH 10/10] oops --- wit/types.wit | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wit/types.wit b/wit/types.wit index 002bed9..30b3642 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -154,7 +154,7 @@ interface types { /// /// This type has been deprecated in favor of the `field-name` type. @since(version = 0.2.0) - @deprecated(version = 0.2.1) + @deprecated(version = 0.2.2) type field-key = string; /// Field values should always be ASCII strings. However, in