Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add ready promise and close reason #12

Merged
merged 2 commits into from
Sep 29, 2023
Merged

Add ready promise and close reason #12

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a6575c5
Add ready promise and close reason
jasnell Sep 8, 2023
7c7dcff
Rename `ready` to `opened`
jasnell Sep 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 16 additions & 5 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ const tls_socket = new TLSSocket({ key: '...', cert: '...' });
tls_socket.connect();
</pre>

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/).
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/).

<h2 id="socket-section">Socket</h2>

Expand Down Expand Up @@ -94,8 +94,10 @@ interface Socket {
readonly attribute ReadableStream readable;
readonly attribute WritableStream writable;

readonly attribute Promise&lt;undefined> ready;
jasnell marked this conversation as resolved.
Show resolved Hide resolved

readonly attribute Promise&lt;undefined> closed;
Promise&lt;undefined> close();
Promise&lt;undefined> close(optional any reason);

[NewObject] Socket startTls();
};
Expand Down Expand Up @@ -154,6 +156,11 @@ The {{writable}} attribute is a {{WritableStream}} which sends data to the serve
</pre>
</div>

<h4 id="ready-attribute">ready</h4>

The {{ready}} attribute is a promise that is resolved when the socket connection has been
successfully established, or is rejected if the connection fails.

<h4 id="closed-attribute">closed</h4>

The {{closed}} attribute is a promise which can be used to keep track of the socket state. It gets resolved under the
Expand All @@ -165,7 +172,7 @@ following circumstances:
</ul>

<div class="note">
The current Cloudflare Workers implementation behaves as described above, specifically the
The current Cloudflare Workers implementation behaves as described above, specifically the
ReadableStream needs to be read until completion for the `closed` promise to resolve, if the
ReadableStream is not read then even if the server closes the connection the `closed` promise
will not resolve.
Expand All @@ -184,10 +191,14 @@ Cancelling the socket's ReadableStream and closing the socket's WritableStream d

<h3 id="methods">Methods</h3>

<h4 id="close-method">close()</h4>
<h4 id="close-method">close(optional any reason)</h4>

The {{close()}} method closes the socket and its underlying connection. It returns the same promise as the {{closed}} attribute.

When called, the {{ReadableStream}} and {{WritableStream}} associated with the {{Socket}} will
be canceled and aborted, respectively. If the {{reason}} argument is specified, the {{reason}}
jasnell marked this conversation as resolved.
Show resolved Hide resolved
will be passed on to both the {{ReadableStream}} and {{WritableStream}}.

<h4 id="starttls-method">startTls()</h4>

The {{startTls()}} method enables opportunistic TLS (otherwise known as [StartTLS](https://en.wikipedia.org/wiki/Opportunistic_TLS)) which is a requirement for some protocols (primarily postgres/mysql and other DB protocols).
Expand Down Expand Up @@ -284,7 +295,7 @@ At any point during the creation of the {{Socket}} instance, `connect` may throw
{{secureTransport}} member
</dt>
<dd>
The secure transport mode to use.
The secure transport mode to use.
<dl>
<dt>{{off}}</dt>
<dd>A connection is established in plain text.</dd>
Expand Down