From 36a14ba77647ac37bd1533e0ef7e5f150f7f6dde Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sun, 5 Nov 2023 21:40:39 +0000 Subject: [PATCH 1/5] Update index.bs --- index.bs | 4 ---- 1 file changed, 4 deletions(-) diff --git a/index.bs b/index.bs index a4ae9ab..46df777 100644 --- a/index.bs +++ b/index.bs @@ -114,10 +114,6 @@ The terms {{ReadableStream}} and {{WritableStream}} are defined in [[WHATWG-STRE

Attributes

-

info

- -The {{info}} attribute is a {{SocketInfo}} which contains information about the state of the socket. -

readable

The {{readable}} attribute is a {{ReadableStream}} which receives data from the server the socket is connected to. From 226f2fb218481ba35bda2d8e09b692c2651e4015 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sun, 5 Nov 2023 21:45:23 +0000 Subject: [PATCH 2/5] Update index.bs --- index.bs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/index.bs b/index.bs index 46df777..69abfea 100644 --- a/index.bs +++ b/index.bs @@ -8,6 +8,7 @@ URL: https://sockets-api.proposal.wintercg.org/ Repository: https://github.com/wintercg/proposal-sockets-api Editor: Dominik Picheta, Cloudflare https://cloudflare.com/, dominik@cloudflare.com Editor: Ethan Arrowood, Vercel https://vercel.com/, ethan.arrowood@vercel.com +Editor: James M Snell, Cloudflare https://cloudflare.com/, jsnell@cloudflare.com Abstract: Sockets API for Non-Browser EcmaScript-based runtimes. Markup Shorthands: markdown yes Markup Shorthands: idl yes @@ -42,6 +43,8 @@ A socket becomes closed when its {{close()}} method is called. A socket c

Connect

+

The [=connect=] method here is defined in a `sockets` module here only for initial implementation purposes. It is imagined that in a finalized standard definition, the [=connect=] would be exposed as a global or within a [=binding object=]

+ A socket can be constructed using a connect method defined in a `sockets` module (early implementations may use `vendor:sockets` for the module name), or defined on a [=binding object=]. The connect method is the primary mechanism for creating a [=socket=] instance. It instantiates a socket with a resource identifier and some configuration values. It should synchronously return a socket instance in a pending state (or an error should be thrown). The socket will asynchronously connect depending on the implementation. From 18493238e61c622febf048b3de0684f134c2e107 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sun, 5 Nov 2023 22:12:47 +0000 Subject: [PATCH 3/5] Update index.bs --- index.bs | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/index.bs b/index.bs index 69abfea..a28b324 100644 --- a/index.bs +++ b/index.bs @@ -51,6 +51,8 @@ The connect method is the primary mechanism for creating a [=socket=] instance.

Binding Object

+

A [=binding object=] in this context is essentially just an object that exposes the a [=connect=] method conformant with this specification. It is anticipated that a runtime may have any number of such objects. This is an area where there is still active discussion on how this should be defined.

+ The binding object defines extra socket `connect` options. The options it contains can modify the behaviour of the `connect` invoked on it. Some of the options it can define: @@ -63,7 +65,7 @@ The binding object is the primary mechanism for runtimes to introduce unique beh 
 const tls_socket = new TLSSocket({ key: '...', cert: '...' });
-tls_socket.connect();
+tls_socket.connect("example.com:1234");
Additionally, the binding object does not necessarily have to be an instance of a class, nor does it even have to be JavaScript. It can be any mechanism that exposes the {{connect()}} method. Cloudflare achieves this through [environment bindings](https://developers.cloudflare.com/workers/configuration/bindings/). @@ -145,9 +147,7 @@ The {{readable}} attribute is a {{ReadableStream}} which receives data from the -The ReadableStream operates in non-byte mode, that is the `type` parameter to the -ReadableStream constructor is not set. -This means the stream's controller is {{ReadableStreamDefaultController}}. +The ReadableStream currently is defined to operate in byte mode, that is the `type` parameter to the ReadableStream constructor is set to `'bytes'`. This means the stream's controller is {{ReadableByteStreamDController}}.

writable

@@ -253,6 +253,8 @@ The method must fail with an [=SocketError=] if:

SocketError

+

Arguably, this should be a type of {{DOMException}} rather than {{TypeError}}. More discussion is necessary on the form and structure of socket-related errors.

+ SocketError is an instance of {{TypeError}}. The error message should start with `"SocketError: "`.
@@ -299,11 +301,11 @@ The {{connect()}} method performs the following steps:
  • The created {{Socket}} instance is returned immediately in a pending state.
  • A connection is established to the specified {{SocketAddress}} asynchronously.
  • Once the connection is established, set |info| to a new {{SocketInfo}}, and [=Resolve=] |opened| with |info|. For a socket using secure transport, the connection is considered to be established once the secure handshake has been completed.
    • -
  • If the connection fails for any reason, the socket's {{closed}} and {{opened}} promises are rejected with a [=SocketError=] describing why the connection failed.
    • -
  • The instance's {{ReadableStream}} and {{WritableStream}} streams can be used immediately.
    • +
  • If the connection fails for any reason, set |error| to a new [=SocketError=] and reject the socket's {{closed}} and {{opened}} promises with |error|. Also, the {{readable}} is canceled with |error| and the {{writable}} is aborted with |error|.
    • +
  • The instance's {{ReadableStream}} and {{WritableStream}} streams can be used immediately but may not actually transmit or receive data until the socket is fully opened.
    • -At any point during the creation of the {{Socket}} instance, `connect` may throw a [=SocketError=]. One case where this can happen is if the input address is incorrectly formatted. Errors which occur asynchronously (after the socket instance has been returned) must reject the socket's {{closed}} promise. +At any point during the creation of the {{Socket}} instance, `connect` may throw a [=SocketError=]. One case where this can happen is if the input address is incorrectly formatted.
    The implementation may consider blocking connections to certain hostname/port combinations which can pose a threat of abuse or security vulnerability. From 2356552bc1f7f182ac1e8a0094290fa5db38c482 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sun, 5 Nov 2023 22:16:21 +0000 Subject: [PATCH 4/5] Update index.bs --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index a28b324..19f53ff 100644 --- a/index.bs +++ b/index.bs @@ -147,7 +147,7 @@ The {{readable}} attribute is a {{ReadableStream}} which receives data from the
    -The ReadableStream currently is defined to operate in byte mode, that is the `type` parameter to the ReadableStream constructor is set to `'bytes'`. This means the stream's controller is {{ReadableByteStreamDController}}. +

    The ReadableStream currently is defined to operate in non-byte mode, that is the `type` parameter to the ReadableStream constructor is not set. This means the stream's controller is {{ReadableStreamDefaultController}}. This, however, should be discussed and may be made configurable. It is reasonable, for instance, to assume that sockets used for most TCP cases would be byte-oriented, while sockets used for messages (e.g. UDP) would not.

    writable

    From f23540bd24dd81de43a2cf1b8e1a99600cc918df Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 6 Nov 2023 14:14:18 +0000 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Dominik Picheta --- index.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index 19f53ff..957fadc 100644 --- a/index.bs +++ b/index.bs @@ -43,7 +43,7 @@ A socket becomes closed when its {{close()}} method is called. A socket c

    Connect

    -

    The [=connect=] method here is defined in a `sockets` module here only for initial implementation purposes. It is imagined that in a finalized standard definition, the [=connect=] would be exposed as a global or within a [=binding object=]

    +

    The [=connect=] method here is defined in a `sockets` module only for initial implementation purposes. It is imagined that in a finalized standard definition, the [=connect=] would be exposed as a global or within a [=binding object=]

    A socket can be constructed using a connect method defined in a `sockets` module (early implementations may use `vendor:sockets` for the module name), or defined on a [=binding object=]. @@ -51,7 +51,7 @@ The connect method is the primary mechanism for creating a [=socket=] instance.

    Binding Object

    -

    A [=binding object=] in this context is essentially just an object that exposes the a [=connect=] method conformant with this specification. It is anticipated that a runtime may have any number of such objects. This is an area where there is still active discussion on how this should be defined.

    +

    A [=binding object=] in this context is essentially just an object that exposes a [=connect=] method conformant with this specification. It is anticipated that a runtime may have any number of such objects. This is an area where there is still active discussion on how this should be defined.

    The binding object defines extra socket `connect` options. The options it contains can modify the behaviour of the `connect` invoked on it. Some of the options it can define: