@bytecodealliance/preview2-shim 0.0.21 → 0.14.1

package/types/interfaces/wasi-http-types.d.ts

@@ -1,7 +1,29 @@
 export namespace WasiHttpTypes {
+  /**
+   * Attempts to extract a http-related `error` from the wasi:io `error`
+   * provided.
+   * 
+   * Stream operations which return
+   * `wasi:io/stream/stream-error::last-operation-failed` have a payload of
+   * type `wasi:io/error/error` with more information about the operation
+   * that failed. This payload can be passed through to this function to see
+   * if there's http-related information about the error to return.
+   * 
+   * Note that this function is fallible because not all io-errors are
+   * http-related errors.
+   */
+  export function httpErrorCode(err: IoError): ErrorCode | undefined;
+  /**
+   * Construct an empty HTTP Fields.
+   * 
+   * The resulting `fields` is mutable.
+   */
+  export { Fields };
   /**
    * Construct an HTTP Fields.
    * 
+   * The resulting `fields` is mutable.
+   * 
    * The 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.
@@ -10,22 +32,30 @@ export namespace WasiHttpTypes {
    * Value, represented as a list of bytes. In a valid Fields, all keys
    * and values are valid UTF-8 strings. However, values are not always
    * well-formed, so they are represented as a raw list of bytes.
+   * 
+   * An error result will be returned if any header or value was
+   * syntactically invalid, or if a header was forbidden.
    */
-  export { Fields };
   /**
    * Get all of the values corresponding to a key.
    */
   /**
    * 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.
    */
   /**
    * 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.
    */
   /**
    * 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.
    */
   /**
    * Retrieve the full set of keys and values in the Fields. Like the
@@ -37,7 +67,8 @@ export namespace WasiHttpTypes {
    */
   /**
    * Make a deep copy of the Fields. Equivelant in behavior to calling the
-   * `fields` constructor on the return value of `entries`
+   * `fields` constructor on the return value of `entries`. The resulting
+   * `fields` is mutable.
    */
   /**
    * Returns the method of the incoming request.
@@ -53,7 +84,10 @@ export namespace WasiHttpTypes {
    * Returns the authority from the request, if it was present.
    */
   /**
-   * Returns the `headers` from the request.
+   * Get the `headers` associated with the request.
+   * 
+   * The returned `headers` resource is immutable: `set`, `append`, and
+   * `delete` operations will fail with `header-error.immutable`.
    * 
    * The `headers` returned are a child resource: it must be dropped before
    * the parent `incoming-request` is dropped. Dropping this
@@ -64,12 +98,98 @@ export namespace WasiHttpTypes {
    * return success at most once, and subsequent calls will return error.
    */
   /**
-   * Construct a new `outgoing-request`.
+   * Construct a new `outgoing-request` with a default `method` of `GET`, and
+   * `none` values for `path-with-query`, `scheme`, and `authority`.
+   * 
+   * * `headers` is the HTTP Headers for the Request.
+   * 
+   * It is possible to construct, or manipulate with the accessor functions
+   * below, an `outgoing-request` with an invalid combination of `scheme`
+   * and `authority`, or `headers` which are not permitted to be sent.
+   * It is the obligation of the `outgoing-handler.handle` implementation
+   * to reject invalid constructions of `outgoing-request`.
    */
   export { OutgoingRequest };
   /**
-   * Will return the outgoing-body child at most once. If called more than
-   * once, subsequent calls will return error.
+   * Returns the resource corresponding to the outgoing Body for this
+   * Request.
+   * 
+   * Returns success on the first call: the `outgoing-body` resource for
+   * this `outgoing-request` can be retrieved at most once. Subsequent
+   * calls will return error.
+   */
+  /**
+   * Get the Method for the Request.
+   */
+  /**
+   * Set the Method for the Request. Fails if the string present in a
+   * `method.other` argument is not a syntactically valid method.
+   */
+  /**
+   * Get the combination of the HTTP Path and Query for the Request.
+   * When `none`, this represents an empty Path and empty Query.
+   */
+  /**
+   * 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.
+   */
+  /**
+   * Get the HTTP Related Scheme for the Request. When `none`, the
+   * implementation may choose an appropriate default scheme.
+   */
+  /**
+   * 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.
+   */
+  /**
+   * Get the HTTP Authority for the Request. 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.
+   */
+  /**
+   * Set the HTTP Authority for the Request. 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.
+   */
+  /**
+   * Get the headers associated with the Request.
+   * 
+   * The returned `headers` resource is immutable: `set`, `append`, and
+   * `delete` operations will fail with `header-error.immutable`.
+   * 
+   * This headers resource is a child: it must be dropped before the parent
+   * `outgoing-request` is dropped, or its ownership is transfered to
+   * another component by e.g. `outgoing-handler.handle`.
+   */
+  /**
+   * Construct a default `request-options` value.
+   */
+  export { RequestOptions };
+  /**
+   * The timeout for the initial connect to the HTTP Server.
+   */
+  /**
+   * Set the timeout for the initial connect to the HTTP Server. An error
+   * return value indicates that this timeout is not supported.
+   */
+  /**
+   * The timeout for receiving the first byte of the Response body.
+   */
+  /**
+   * Set the timeout for receiving the first byte of the Response body. An
+   * error return value indicates that this timeout is not supported.
+   */
+  /**
+   * The timeout for receiving subsequent chunks of bytes in the Response
+   * body stream.
+   */
+  /**
+   * 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.
    */
   /**
    * Set the value of the `response-outparam` to either send a response,
@@ -78,6 +198,9 @@ export namespace WasiHttpTypes {
    * This method consumes the `response-outparam` to ensure that it is
    * called at most once. If it is never called, the implementation
    * will respond with an error.
+   * 
+   * The user may provide an `error` to `response` to allow the
+   * implementation determine how to respond with an HTTP error response.
    */
   export { ResponseOutparam };
   /**
@@ -86,6 +209,12 @@ export namespace WasiHttpTypes {
   export { IncomingResponse };
   /**
    * Returns the headers from the incoming response.
+   * 
+   * The returned `headers` resource is immutable: `set`, `append`, and
+   * `delete` operations will fail with `header-error.immutable`.
+   * 
+   * This headers resource is a child: it must be dropped before the parent
+   * `incoming-response` is dropped.
    */
   /**
    * Returns the incoming body. May be called at most once. Returns error
@@ -128,20 +257,45 @@ export namespace WasiHttpTypes {
    * 
    * The `result` represents that either the HTTP Request or Response body,
    * as well as any trailers, were received successfully, or that an error
-   * occured receiving them.
+   * occured receiving them. The optional `trailers` indicates whether or not
+   * trailers were present in the body.
+   * 
+   * When some `trailers` are returned by this method, the `trailers`
+   * resource is immutable, and a child. Use of the `set`, `append`, or
+   * `delete` methods will return an error, and the resource must be
+   * dropped before the parent `future-trailers` is dropped.
    */
   /**
-   * Construct an `outgoing-response`.
+   * 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.
+   * 
+   * * `headers` is the HTTP Headers for the Response.
    */
   export { OutgoingResponse };
+  /**
+   * Get the HTTP Status Code for the Response.
+   */
+  /**
+   * Set the HTTP Status Code for the Response. Fails if the status-code
+   * given is not a valid http status code.
+   */
+  /**
+   * Get the headers associated with the Request.
+   * 
+   * The returned `headers` resource is immutable: `set`, `append`, and
+   * `delete` operations will fail with `header-error.immutable`.
+   * 
+   * This headers resource is a child: it must be dropped before the parent
+   * `outgoing-request` is dropped, or its ownership is transfered to
+   * another component by e.g. `outgoing-handler.handle`.
+   */
   /**
    * 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. Sunsequent
+   * this `outgoing-response` can be retrieved at most once. Subsequent
    * calls will return error.
-   * 
-   * FIXME: rename this method to `body`.
    */
   /**
    * Returns a stream for writing the body contents.
@@ -160,6 +314,11 @@ export namespace WasiHttpTypes {
    * called to signal that the response is complete. If the `outgoing-body`
    * is dropped without calling `outgoing-body.finalize`, the implementation
    * should treat the body as corrupted.
+   * 
+   * Fails if the body's `outgoing-request` or `outgoing-response` was
+   * constructed with a Content-Length header, and the contents written
+   * to the body (via `write`) does not match the value given in the
+   * Content-Length.
    */
   /**
    * Returns a pollable which becomes ready when either the Response has
@@ -184,10 +343,14 @@ export namespace WasiHttpTypes {
    * `output-stream` child.
    */
 }
+import type { Duration } from '../interfaces/wasi-clocks-monotonic-clock.js';
+export { Duration };
 import type { InputStream } from '../interfaces/wasi-io-streams.js';
 export { InputStream };
 import type { OutputStream } from '../interfaces/wasi-io-streams.js';
 export { OutputStream };
+import type { IoError } from '../interfaces/wasi-io-error.js';
+export { IoError };
 import type { Pollable } from '../interfaces/wasi-io-poll.js';
 export { Pollable };
 /**
@@ -240,26 +403,196 @@ export interface SchemeOther {
   val: string,
 }
 /**
- * TODO: perhaps better align with HTTP semantics?
- * This type enumerates the different kinds of errors that may occur when
- * initially returning a response.
+ * Defines the case payload type for `DNS-error` above:
  */
-export type Error = ErrorInvalidUrl | ErrorTimeoutError | ErrorProtocolError | ErrorUnexpectedError;
-export interface ErrorInvalidUrl {
-  tag: 'invalid-url',
-  val: string,
+export interface DnsErrorPayload {
+  rcode?: string,
+  infoCode?: number,
 }
-export interface ErrorTimeoutError {
-  tag: 'timeout-error',
-  val: string,
+/**
+ * Defines the case payload type for `TLS-alert-received` above:
+ */
+export interface TlsAlertReceivedPayload {
+  alertId?: number,
+  alertMessage?: string,
 }
-export interface ErrorProtocolError {
-  tag: 'protocol-error',
-  val: string,
+/**
+ * Defines the case payload type for `HTTP-response-{header,trailer}-size` above:
+ */
+export interface FieldSizePayload {
+  fieldName?: string,
+  fieldSize?: number,
 }
-export interface ErrorUnexpectedError {
-  tag: 'unexpected-error',
-  val: string,
+/**
+ * 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
+ */
+export type ErrorCode = ErrorCodeDnsTimeout | ErrorCodeDnsError | ErrorCodeDestinationNotFound | ErrorCodeDestinationUnavailable | ErrorCodeDestinationIpProhibited | ErrorCodeDestinationIpUnroutable | ErrorCodeConnectionRefused | ErrorCodeConnectionTerminated | ErrorCodeConnectionTimeout | ErrorCodeConnectionReadTimeout | ErrorCodeConnectionWriteTimeout | ErrorCodeConnectionLimitReached | ErrorCodeTlsProtocolError | ErrorCodeTlsCertificateError | ErrorCodeTlsAlertReceived | ErrorCodeHttpRequestDenied | ErrorCodeHttpRequestLengthRequired | ErrorCodeHttpRequestBodySize | ErrorCodeHttpRequestMethodInvalid | ErrorCodeHttpRequestUriInvalid | ErrorCodeHttpRequestUriTooLong | ErrorCodeHttpRequestHeaderSectionSize | ErrorCodeHttpRequestHeaderSize | ErrorCodeHttpRequestTrailerSectionSize | ErrorCodeHttpRequestTrailerSize | ErrorCodeHttpResponseIncomplete | ErrorCodeHttpResponseHeaderSectionSize | ErrorCodeHttpResponseHeaderSize | ErrorCodeHttpResponseBodySize | ErrorCodeHttpResponseTrailerSectionSize | ErrorCodeHttpResponseTrailerSize | ErrorCodeHttpResponseTransferCoding | ErrorCodeHttpResponseContentCoding | ErrorCodeHttpResponseTimeout | ErrorCodeHttpUpgradeFailed | ErrorCodeHttpProtocolError | ErrorCodeLoopDetected | ErrorCodeConfigurationError | ErrorCodeInternalError;
+export interface ErrorCodeDnsTimeout {
+  tag: 'DNS-timeout',
+}
+export interface ErrorCodeDnsError {
+  tag: 'DNS-error',
+  val: DnsErrorPayload,
+}
+export interface ErrorCodeDestinationNotFound {
+  tag: 'destination-not-found',
+}
+export interface ErrorCodeDestinationUnavailable {
+  tag: 'destination-unavailable',
+}
+export interface ErrorCodeDestinationIpProhibited {
+  tag: 'destination-IP-prohibited',
+}
+export interface ErrorCodeDestinationIpUnroutable {
+  tag: 'destination-IP-unroutable',
+}
+export interface ErrorCodeConnectionRefused {
+  tag: 'connection-refused',
+}
+export interface ErrorCodeConnectionTerminated {
+  tag: 'connection-terminated',
+}
+export interface ErrorCodeConnectionTimeout {
+  tag: 'connection-timeout',
+}
+export interface ErrorCodeConnectionReadTimeout {
+  tag: 'connection-read-timeout',
+}
+export interface ErrorCodeConnectionWriteTimeout {
+  tag: 'connection-write-timeout',
+}
+export interface ErrorCodeConnectionLimitReached {
+  tag: 'connection-limit-reached',
+}
+export interface ErrorCodeTlsProtocolError {
+  tag: 'TLS-protocol-error',
+}
+export interface ErrorCodeTlsCertificateError {
+  tag: 'TLS-certificate-error',
+}
+export interface ErrorCodeTlsAlertReceived {
+  tag: 'TLS-alert-received',
+  val: TlsAlertReceivedPayload,
+}
+export interface ErrorCodeHttpRequestDenied {
+  tag: 'HTTP-request-denied',
+}
+export interface ErrorCodeHttpRequestLengthRequired {
+  tag: 'HTTP-request-length-required',
+}
+export interface ErrorCodeHttpRequestBodySize {
+  tag: 'HTTP-request-body-size',
+  val: bigint | undefined,
+}
+export interface ErrorCodeHttpRequestMethodInvalid {
+  tag: 'HTTP-request-method-invalid',
+}
+export interface ErrorCodeHttpRequestUriInvalid {
+  tag: 'HTTP-request-URI-invalid',
+}
+export interface ErrorCodeHttpRequestUriTooLong {
+  tag: 'HTTP-request-URI-too-long',
+}
+export interface ErrorCodeHttpRequestHeaderSectionSize {
+  tag: 'HTTP-request-header-section-size',
+  val: number | undefined,
+}
+export interface ErrorCodeHttpRequestHeaderSize {
+  tag: 'HTTP-request-header-size',
+  val: FieldSizePayload | undefined,
+}
+export interface ErrorCodeHttpRequestTrailerSectionSize {
+  tag: 'HTTP-request-trailer-section-size',
+  val: number | undefined,
+}
+export interface ErrorCodeHttpRequestTrailerSize {
+  tag: 'HTTP-request-trailer-size',
+  val: FieldSizePayload,
+}
+export interface ErrorCodeHttpResponseIncomplete {
+  tag: 'HTTP-response-incomplete',
+}
+export interface ErrorCodeHttpResponseHeaderSectionSize {
+  tag: 'HTTP-response-header-section-size',
+  val: number | undefined,
+}
+export interface ErrorCodeHttpResponseHeaderSize {
+  tag: 'HTTP-response-header-size',
+  val: FieldSizePayload,
+}
+export interface ErrorCodeHttpResponseBodySize {
+  tag: 'HTTP-response-body-size',
+  val: bigint | undefined,
+}
+export interface ErrorCodeHttpResponseTrailerSectionSize {
+  tag: 'HTTP-response-trailer-section-size',
+  val: number | undefined,
+}
+export interface ErrorCodeHttpResponseTrailerSize {
+  tag: 'HTTP-response-trailer-size',
+  val: FieldSizePayload,
+}
+export interface ErrorCodeHttpResponseTransferCoding {
+  tag: 'HTTP-response-transfer-coding',
+  val: string | undefined,
+}
+export interface ErrorCodeHttpResponseContentCoding {
+  tag: 'HTTP-response-content-coding',
+  val: string | undefined,
+}
+export interface ErrorCodeHttpResponseTimeout {
+  tag: 'HTTP-response-timeout',
+}
+export interface ErrorCodeHttpUpgradeFailed {
+  tag: 'HTTP-upgrade-failed',
+}
+export interface ErrorCodeHttpProtocolError {
+  tag: 'HTTP-protocol-error',
+}
+export interface ErrorCodeLoopDetected {
+  tag: 'loop-detected',
+}
+export interface ErrorCodeConfigurationError {
+  tag: 'configuration-error',
+}
+/**
+ * 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.
+ */
+export interface ErrorCodeInternalError {
+  tag: 'internal-error',
+  val: string | undefined,
+}
+/**
+ * This type enumerates the different kinds of errors that may occur when
+ * setting or appending to a `fields` resource.
+ */
+export type HeaderError = HeaderErrorInvalidSyntax | HeaderErrorForbidden | HeaderErrorImmutable;
+/**
+ * This error indicates that a `field-key` or `field-value` was
+ * syntactically invalid when used with an operation that sets headers in a
+ * `fields`.
+ */
+export interface HeaderErrorInvalidSyntax {
+  tag: 'invalid-syntax',
+}
+/**
+ * This error indicates that a forbidden `field-key` was used when trying
+ * to set a header in a `fields`.
+ */
+export interface HeaderErrorForbidden {
+  tag: 'forbidden',
+}
+/**
+ * This error indicates that the operation on the `fields` was not
+ * permitted because the fields are immutable.
+ */
+export interface HeaderErrorImmutable {
+  tag: 'immutable',
 }
 /**
  * Field keys are always strings.
@@ -279,59 +612,20 @@ export type Headers = Fields;
  * Trailers is an alias for Fields.
  */
 export type Trailers = Fields;
-/**
- * Parameters for making an HTTP Request. Each of these parameters is an
- * optional timeout, with the unit in milliseconds, 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-list`.
- * 
- * FIXME: Make this a resource to allow it to be optionally extended by
- * future evolution of the standard and/or other interfaces at some later
- * date?
- */
-export interface RequestOptions {
-  /**
-   * The timeout for the initial connect to the HTTP Server.
-   */
-  connectTimeoutMs?: number,
-  /**
-   * The timeout for receiving the first byte of the Response body.
-   */
-  firstByteTimeoutMs?: number,
-  /**
-   * The timeout for receiving subsequent chunks of bytes in the Response
-   * body stream.
-   */
-  betweenBytesTimeoutMs?: number,
-}
 /**
  * This type corresponds to the HTTP standard Status Code.
  */
 export type StatusCode = number;
+export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };
 
-export class OutgoingRequest {
-  constructor(method: Method, pathWithQuery: string | undefined, scheme: Scheme | undefined, authority: string | undefined, headers: Headers)
-  write(): OutgoingBody;
-}
-
-export class IncomingBody {
-  stream(): InputStream;
-  static finish(this_: IncomingBody): FutureTrailers;
-}
-
-export class ResponseOutparam {
-  static set(param: ResponseOutparam, response: Result<OutgoingResponse, Error>): void;
-}
-
-export class OutgoingResponse {
-  constructor(statusCode: StatusCode, headers: Headers)
-  write(): OutgoingBody;
+export class FutureIncomingResponse {
+  subscribe(): Pollable;
+  get(): Result<Result<IncomingResponse, ErrorCode>, void> | undefined;
 }
 
 export class Fields {
-  constructor(entries: [FieldKey, FieldValue][])
+  constructor()
+  static fromList(entries: [FieldKey, FieldValue][]): Fields;
   get(name: FieldKey): FieldValue[];
   set(name: FieldKey, value: FieldValue[]): void;
   delete(name: FieldKey): void;
@@ -342,18 +636,40 @@ export class Fields {
 
 export class FutureTrailers {
   subscribe(): Pollable;
-  get(): Result<Trailers, Error> | undefined;
+  get(): Result<Trailers | undefined, ErrorCode> | undefined;
 }
 
-export class IncomingResponse {
-  status(): StatusCode;
+export class OutgoingRequest {
+  constructor(headers: Headers)
+  body(): OutgoingBody;
+  method(): Method;
+  setMethod(method: Method): void;
+  pathWithQuery(): string | undefined;
+  setPathWithQuery(pathWithQuery: string | undefined): void;
+  scheme(): Scheme | undefined;
+  setScheme(scheme: Scheme | undefined): void;
+  authority(): string | undefined;
+  setAuthority(authority: string | undefined): void;
   headers(): Headers;
-  consume(): IncomingBody;
 }
 
-export class OutgoingBody {
-  write(): OutputStream;
-  static finish(this_: OutgoingBody, trailers: Trailers | undefined): void;
+export class RequestOptions {
+  constructor()
+  connectTimeoutMs(): Duration | undefined;
+  setConnectTimeoutMs(ms: Duration | undefined): void;
+  firstByteTimeoutMs(): Duration | undefined;
+  setFirstByteTimeoutMs(ms: Duration | undefined): void;
+  betweenBytesTimeoutMs(): Duration | undefined;
+  setBetweenBytesTimeoutMs(ms: Duration | undefined): void;
+}
+
+export class IncomingBody {
+  stream(): InputStream;
+  static finish(this_: IncomingBody): FutureTrailers;
+}
+
+export class ResponseOutparam {
+  static set(param: ResponseOutparam, response: Result<OutgoingResponse, ErrorCode>): void;
 }
 
 export class IncomingRequest {
@@ -365,7 +681,21 @@ export class IncomingRequest {
   consume(): IncomingBody;
 }
 
-export class FutureIncomingResponse {
-  subscribe(): Pollable;
-  get(): Result<Result<IncomingResponse, Error>, void> | undefined;
+export class OutgoingResponse {
+  constructor(headers: Headers)
+  statusCode(): StatusCode;
+  setStatusCode(statusCode: StatusCode): void;
+  headers(): Headers;
+  body(): OutgoingBody;
+}
+
+export class IncomingResponse {
+  status(): StatusCode;
+  headers(): Headers;
+  consume(): IncomingBody;
+}
+
+export class OutgoingBody {
+  write(): OutputStream;
+  static finish(this_: OutgoingBody, trailers: Trailers | undefined): void;
 }

package/types/interfaces/wasi-io-error.d.ts

@@ -0,0 +1,16 @@
+export namespace WasiIoError {
+  /**
+   * Returns a string that is suitable to assist humans in debugging
+   * this error.
+   * 
+   * WARNING: The returned string should not be consumed mechanically!
+   * It may change across platforms, hosts, or other implementation
+   * details. Parsing this string is a major platform-compatibility
+   * hazard.
+   */
+  export { Error };
+}
+
+export class Error {
+  toDebugString(): string;
+}

package/types/interfaces/wasi-io-poll.d.ts

@@ -1,4 +1,17 @@
 export namespace WasiIoPoll {
+  /**
+   * Return the readiness of a pollable. This function never blocks.
+   * 
+   * Returns `true` when the pollable is ready, and `false` otherwise.
+   */
+  export { Pollable };
+  /**
+   * `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.
+   */
   /**
    * Poll for completion on a set of pollables.
    * 
@@ -19,12 +32,10 @@ export namespace WasiIoPoll {
    * the pollables has an error, it is indicated by marking the source as
    * being reaedy for I/O.
    */
-  export function pollList(in_: Pollable[]): Uint32Array;
-  /**
-   * Poll for completion on a single pollable.
-   * 
-   * This function is similar to `poll-list`, but operates on only a single
-   * pollable. When it returns, the handle is ready for I/O.
-   */
-  export function pollOne(in_: Pollable): void;
+  export function poll(in_: Pollable[]): Uint32Array;
+}
+
+export class Pollable {
+  ready(): boolean;
+  block(): void;
 }