silk.http.websocket_native.

When to use#

Call connect to open a client session to a ws or wss URI. Call split on a session over a NativeTransport, from connect or from acceptOwned of silk.http.websocket_upgrade, so that one fiber reads while other fibers send.

Details#

connect opens the connection with acquireOwned of silk.http.exchange_native, then calls handshake of silk.http.websocket_client. A wss URI uses TLS with the trust snapshot that you give, and offers only HTTP/1.1 in ALPN.

split splits the socket, and for TLS the session, so the reader and the writers do not wait for each other.

Errors#

connect fails with the errors of the connection and of the handshake. OriginError if the URI is not a ws, wss, http, or https URI.

Gotchas#

• With a host name, the deadline of the options must be None, as for acquireOwned.

• The session does not close the transport. Close it when the session is Closed or failed.

Examples#

Split an accepted session#

import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.http.exchange_native { NativeTransport }
import silk.http.websocket_native { split }
import silk.http.websocket_stream { Split, WebSocket }

// Splits `socket`, so a fiber can read with the reader while others send with the writer.
effect fn halves(socket: WebSocket<NativeTransport>) -> Split<NativeTransport, NativeTransport>
  ! OutOfMemoryError
  ? &mut Allocator {
  return run split(move socket)
}

pub fn main() -> i32 {
  return 0
}

Import as WebSocketNative with import silk.http.websocket_native as WebSocketNative.

Public declarations: 2.

connect#

pub effect fn connect<'value>(
  uri: &Uri<'value>,
  headers: &Headers<'value>,
  options: ClientOptions<'value>,
  native: NativeOptions,
  preparedTrust: Option<TrustSnapshot>,
) -> Opened<NativeTransport>
! OriginError | NativeExchangeError | ResolverError | NativeSocketError | ConnectionError | IdentityError | HandshakeError | ExchangeError | RequestError | StreamError | OutOfMemoryError
? &mut Allocator | &mut MonotonicClock | &mut SystemClock | &mut Random

Opens a connection to the origin of uri, sends the opening handshake, and returns the open client session.

Details#

native sets the socket and TLS options. The deadline of options limits the connection too. preparedTrust is needed for wss. headers are sent with the handshake, as for handshake.

Errors#

• OriginError if uri has no valid origin.

• NativeExchangeError, ResolverError, NativeSocketError, ConnectionError, and IdentityError from the connection, as for acquireOwned.

• HandshakeError, ExchangeError, RequestError, and StreamError from the handshake.

• OutOfMemoryError if a buffer cannot grow.

split#

pub effect fn split(socket: WebSocket<NativeTransport>) -> Split<NativeTransport, NativeTransport>
! OutOfMemoryError
? &mut Allocator

Splits a session over a NativeTransport into a reader and a writer.

Errors#

OutOfMemoryError if the shared state cannot be allocated.

Gotchas#

It traps if the transport is already a half.

Category: HTTP.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.