From f27d59e0b6f04c473563bdf60e73e797da6dc204 Mon Sep 17 00:00:00 2001 From: "Jiaxiao Zhou (Mossaka)" Date: Sat, 21 Oct 2023 00:09:45 -0700 Subject: [PATCH 1/3] refactor: use include syntax for wasi:clocks This commit uses `include` syntax to simplify the proxy world by hiding the interfaces from wasi:clock package Signed-off-by: Jiaxiao Zhou (Mossaka) --- wit/proxy.wit | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/wit/proxy.wit b/wit/proxy.wit index 453f590..47a8795 100644 --- a/wit/proxy.wit +++ b/wit/proxy.wit @@ -5,9 +5,8 @@ package wasi:http@0.2.0-rc-2023-11-10; /// this world may concurrently stream in and out any number of incoming and /// outgoing HTTP requests. world proxy { - /// HTTP proxies have access to time and randomness. - import wasi:clocks/wall-clock@0.2.0-rc-2023-11-10; - import wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10; + // HTTP proxies have access to time and randomness. + include wasi:clocks/imports@0.2.0-rc-2023-11-10; import wasi:random/random@0.2.0-rc-2023-11-10; /// Proxies have standard output and error streams which are expected to From cd852a92e3798e79f23dd86b978ec4f957837461 Mon Sep 17 00:00:00 2001 From: "Jiaxiao Zhou (Mossaka)" Date: Thu, 30 Nov 2023 11:58:16 -0800 Subject: [PATCH 2/3] update proxy.md Signed-off-by: Jiaxiao Zhou (Mossaka) --- proxy.md | 294 +++++++++++++++++++++++++++---------------------------- 1 file changed, 147 insertions(+), 147 deletions(-) diff --git a/proxy.md b/proxy.md index 80d0fd2..cf8856d 100644 --- a/proxy.md +++ b/proxy.md @@ -6,17 +6,17 @@ outgoing HTTP requests.

-

Import interface wasi:clocks/wall-clock@0.2.0-rc-2023-11-10

-

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.

+

Import interface wasi:random/random@0.2.0-rc-2023-11-10

+

WASI Random is a random data API.

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

-

A wall clock is a clock which measures the date and time according to -some external reference.

-

External references may be reset, so this clock is not necessarily -monotonic, making it unsuitable for measuring elapsed time.

-

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

-

Types

-

record datetime

-

A time and date in seconds plus nanoseconds.

-
Record Fields
+

Functions

+

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 +number generator (CSPRNG). It must not block, from the perspective of +the calling program, under any circumstances, including on the first +request and on requests for numbers of bytes. The returned data must +always be unpredictable.

+

This function must always return fresh data. Deterministic environments +must omit this function, rather than implementing it with deterministic +data.

+
Params
+
Return values
+
    +
  • list<u8>
    • +
+

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
    • +
+

Import interface wasi:io/error@0.2.0-rc-2023-11-10

+
+

Types

+

resource error

Functions

-

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.

-

The returned timestamps represent the number of seconds since -1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, -also known as Unix Time.

-

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

-
Return values
+

[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! +It may change across platforms, hosts, or other implementation +details. Parsing this string is a major platform-compatibility +hazard.

+
Params
-

resolution: func

-

Query the resolution of the clock.

-

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

Return values

Import interface wasi:io/poll@0.2.0-rc-2023-11-10

A poll API intended to let users wait for I/O events on multiple handles @@ -116,121 +129,6 @@ being reaedy for I/O.

  • list<u32>
-

Import interface wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10

-

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 -Windows.

-

A monotonic clock is a clock which has an unspecified initial value, and -successive reads of the clock will produce non-decreasing values.

-

It is intended for measuring elapsed time.

-
-

Types

-

type pollable

-

pollable

-

-#### `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

-

u64

-

A duration of time, in nanoseconds. -

-

Functions

-

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

-

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

-
Return values
- -

subscribe-instant: func

-

Create a pollable which will resolve once the specified instant -occured.

-
Params
- -
Return values
- -

subscribe-duration: func

-

Create a pollable which will resolve once the given duration has -elapsed, starting at the time at which this function was called. -occured.

-
Params
- -
Return values
- -

Import interface wasi:random/random@0.2.0-rc-2023-11-10

-

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

-

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 -number generator (CSPRNG). It must not block, from the perspective of -the calling program, under any circumstances, including on the first -request and on requests for numbers of bytes. The returned data must -always be unpredictable.

-

This function must always return fresh data. Deterministic environments -must omit this function, rather than implementing it with deterministic -data.

-
Params
- -
Return values
-
    -
  • list<u8>
    • -
-

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
    • -
-

Import interface wasi:io/error@0.2.0-rc-2023-11-10

-
-

Types

-

resource error

-
-

Functions

-

[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! -It may change across platforms, hosts, or other implementation -details. Parsing this string is a major platform-compatibility -hazard.

-
Params
- -
Return values
-
    -
  • string
    • -

Import interface wasi:io/streams@0.2.0-rc-2023-11-10

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

@@ -573,6 +471,67 @@ is ready for reading, before performing the splice.

+

Import interface wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10

+

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 +Windows.

+

A monotonic clock is a clock which has an unspecified initial value, and +successive reads of the clock will produce non-decreasing values.

+

It is intended for measuring elapsed time.

+
+

Types

+

type pollable

+

pollable

+

+#### `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

+

u64

+

A duration of time, in nanoseconds. +

+

Functions

+

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

+

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

+
Return values
+ +

subscribe-instant: func

+

Create a pollable which will resolve once the specified instant +occured.

+
Params
+ +
Return values
+ +

subscribe-duration: func

+

Create a pollable which will resolve once the given duration has +elapsed, starting at the time at which this function was called. +occured.

+
Params
+ +
Return values
+

Import interface wasi:http/types@0.2.0-rc-2023-11-10

This interface defines all of the types and methods for implementing HTTP Requests and Responses, both incoming and outgoing, as well as @@ -1431,6 +1390,47 @@ through the future-incoming-response

  • result<own<future-incoming-response>, error-code>
    • +

    Import interface wasi:clocks/wall-clock@0.2.0-rc-2023-11-10

    +

    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.

    +

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

    +

    A wall clock is a clock which measures the date and time according to +some external reference.

    +

    External references may be reset, so this clock is not necessarily +monotonic, making it unsuitable for measuring elapsed time.

    +

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

    +
    +

    Types

    +

    record datetime

    +

    A time and date in seconds plus nanoseconds.

    +
    Record Fields
    + +
    +

    Functions

    +

    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.

    +

    The returned timestamps represent the number of seconds since +1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, +also known as Unix Time.

    +

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

    +
    Return values
    + +

    resolution: func

    +

    Query the resolution of the clock.

    +

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

    +
    Return values
    +

    Export interface wasi:http/incoming-handler@0.2.0-rc-2023-11-10

    Types

    From 791ac7726e7a64f178c4622020979173b9590e97 Mon Sep 17 00:00:00 2001 From: "Jiaxiao Zhou (Mossaka)" Date: Thu, 30 Nov 2023 12:03:45 -0800 Subject: [PATCH 3/3] one minor change to the comment Signed-off-by: Jiaxiao Zhou (Mossaka) --- wit/proxy.wit | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wit/proxy.wit b/wit/proxy.wit index 47a8795..ee4ff33 100644 --- a/wit/proxy.wit +++ b/wit/proxy.wit @@ -5,7 +5,7 @@ package wasi:http@0.2.0-rc-2023-11-10; /// this world may concurrently stream in and out any number of incoming and /// outgoing HTTP requests. world proxy { - // HTTP proxies have access to time and randomness. + /// HTTP proxies have access to time and randomness. include wasi:clocks/imports@0.2.0-rc-2023-11-10; import wasi:random/random@0.2.0-rc-2023-11-10;