///|
/// A complete WebSocket message received from the Gateway.
#derive(Debug)
pub(all) enum GatewayFrame {
Text(String)
Binary(Bytes)
}
///|
/// The seam between the shard driver and the network: implemented by the
/// real WebSocket connection in production and by an in-memory fake in tests.
pub(open) trait GatewayTransport {
async fn recv(Self) -> GatewayFrame
async fn send(Self, String) -> Unit
async fn close(Self, code~ : Int32) -> Unit
/// Interrupt pending I/O before shutdown joins the receiver. Transports
/// with protected reads/writes must wake them here; the default is a
/// no-op for transports whose I/O is already interrupted by cancellation.
fn abort(Self) -> Unit = _
}
///|
impl GatewayTransport with fn abort(_) {
}
///|
/// Raised by transports when the peer closed the connection. `code` is the
/// WebSocket close code (Discord uses 4xxx application codes), `None` for
/// abnormal/transport-level termination.
#derive(Debug)
pub(all) suberror TransportClosed {
TransportClosed(code~ : Int32?, reason~ : String)
}
///|
priv struct WsTransport {
conn : &@ws.Session
closed : Ref[Bool]
}
///|
/// The largest Gateway message a shard accepts by default, compressed or
/// not: far above anything Discord sends, but a bound on what one message can
/// make the process allocate.
pub const DEFAULT_MAX_MESSAGE_BYTES : Int32 = 67_108_864
///|
/// Raised for a Gateway configuration that cannot work.
#derive(Debug)
pub(all) suberror GatewayConfigError {
/// `max_message_bytes` must be positive.
InvalidMaxMessageBytes(value~ : Int32)
}
///|
/// Check a `max_message_bytes` setting: a limit below 1 refuses every
/// message, so the shard would reconnect forever without seeing Hello.
fn check_max_message_bytes(value : Int32) -> Unit raise GatewayConfigError {
if value < 1 {
raise InvalidMaxMessageBytes(value~)
}
}
///|
impl GatewayTransport for WsTransport with fn recv(self) {
let message = self.conn.recv() catch {
error if @async.is_being_cancelled() => raise error
error => raise transport_error(error)
}
match message {
Text(text) => Text(text)
Binary(data) => Binary(data)
}
}
///|
fn transport_error(error : @ws.WsError) -> TransportClosed {
match error {
@core_ws.WsError(kind=Closed(frame), ..) =>
TransportClosed(
code=if frame.code is (Abnormal | NoStatus) {
None
} else {
Some(frame.code.to_int())
},
reason=frame.reason,
)
// Preserve the portable status even when a JS host sends 4009 instead.
@core_ws.WsError(kind=TooLarge(_), detail~) =>
TransportClosed(code=Some(1009), reason=detail)
_ => TransportClosed(code=None, reason="\{Repr(error)}")
}
}
///|
impl GatewayTransport for WsTransport with fn send(self, text) {
self.conn.send(Text(text)) catch {
error if @async.is_being_cancelled() => raise error
error => {
if error is @core_ws.WsError(kind=TooLarge(_), ..) {
GatewayTransport::close(self, code=1009)
}
raise transport_error(error)
}
}
}
///|
impl GatewayTransport for WsTransport with fn close(self, code~) {
if self.closed.val {
return
}
self.closed.val = true
defer self.conn.abort()
self.conn.close({ code: @ws.CloseCode::from_int(code), reason: "", })
}
///|
impl GatewayTransport for WsTransport with fn abort(self) {
self.conn.abort()
}
///|
/// Connect to the gateway over WebSocket (the default connector). A message
/// larger than `max_message_bytes` ends the connection with local code 1009
/// (Message Too Big); JS hosts that forbid sending 1009 send 4009 instead.
/// The same bound applies to outgoing messages, and on JS to total queued
/// bytes. Discord's opcode heartbeat owns liveness; WebSocket Ping is off.
pub async fn connect_websocket(
url : String,
max_message_bytes~ : Int32 = DEFAULT_MAX_MESSAGE_BYTES,
) -> &GatewayTransport {
check_max_message_bytes(max_message_bytes)
let limits = {
..@ws.WsLimits::default(),
max_frame_bytes: max_message_bytes.max(125),
max_message_bytes,
close_timeout_ms: 1000,
ping_interval_ms: None,
pong_timeout_ms: None,
}
let conn = @ws.connect(url, limits~)
WsTransport::{ conn, closed: Ref(false), }
}