#lang scribble/doc
@(require
  scribble/manual
  (for-label scheme/tcp openssl "../url.ss" "../sockets.ss"))

@title[#:tag "sockets" #:style '(toc)]{WebSockets}

@local-table-of-contents[]

@defmodule[(planet "sockets.ss" ("murphy" "websockets.plt" 1 0))]{

  This module provides an API for WebSockets that is similar to that of packet
  sockets.
  
}

@section{WebSocket Connections}

@defproc[(ws-socket? [v any/c]) any]{

  Checks whether the given value @scheme[v] is a WebSocket.
  
}

@defproc[(ws-socket-url [socket ws-socket?]) ws-url?]{

  Extracts the URL designating the server side end point from a WebSocket.
  
}

@defproc[(ws-socket-protocol [socket ws-socket?]) (or/c string? #f)]{

  Determines the negotiated protocol for a WebSocket, if any.
  See @scheme[ws-connect] and @scheme[ws-listen] for details about how the protocol
  is established.
  
}

@defproc[(ws-connect [url ws-url?]
                     [protocol (or/c string? #f) #f]
                     [ssl-context (or/c ssl-client-context? symbol?) 'tls]) ws-socket?]{

  Connects to a WebSocket server specified by @scheme[url]. Uses a TCP or TLS
  connection as required by the scheme of the WebSocket URL.
                                              
  If @scheme[protocol] is a string, the connection only succeeds if the WebSocket
  server replies with a matching protocol header to indicate that it supports this
  protocol.
  
  The @scheme[ssl-context] argument is ignored for connection with the URL scheme
  @scheme["ws"]. For secure WebSocket connections with the URL scheme @scheme["wss"],
  it can be used to control the setup of the SSL engine. It defaults to a TLS
  connection without any special setup.
  
}

@section{WebSocket Servers}

@defproc[(ws-listener? [v any/c]) any]{

  Checks whether the given value @scheme[v] is a WebSocket listener.
  
}

@defproc[(ws-listen [port (and/c exact-nonnegative-integer? (integer-in 0 65535))]
                    [protocols (listof string?) '()]
                    [ssl-context (or/c ssl-server-context? #f)]
                    [max-queue exact-nonnegative-integer? 4]
                    [reuse? any/c #f] [host (or/c string? #f) #f]) ws-listener?]{

  Starts listening for incoming WebSocket connections on the given TCP @scheme[port].
  @scheme[protocols] is the list of WebSocket protocol strings that will be accepted
  if requested by the client. A connection without any specified protocol is always
  acceptable.
  
  The @scheme[ssl-context] specifies whether the server will accept plain TCP
  connections or encrypted connections. If it is @scheme[#f], a plain TCP listener
  is used, otherwise the argument is passed on to @scheme[ssl-listen] to control
  the setup of the SSL engine.
  
  The arguments @scheme[max-queue], @scheme[reuse?] and @scheme[host] are passed
  on to @scheme[tcp-listen] or @scheme[ssl-listen] as appropriate.
  
}

@defproc[(ws-accept [listener ws-listener?]) ws-socket?]{

  Accepts an incoming WebSocket connection on @scheme[listener] and returns a
  WebSocket that can be used to obtain information about the connection, such as
  the connection URL and protocol, and to communicate with the client.
  
}

@section{Exchanging WebSocket Messages}

@defproc[(ws-send [socket ws-socket?] [frame (or/c bytes? string?)]) any]{

  Sends a message through the WebSocket @scheme[socket]. The message can be either
  a byte string, which will be sent with frame type @scheme[128] and length
  information, or a string, which will be sent with frame type @scheme[0] and
  without length information.
  
}

@defproc[(ws-send-ready-evt [socket ws-socket?]) evt?]{

  Returns a synchronizable event that becomes ready when data can be written to
  the WebSocket @scheme[socket] and returns the socket itself when chosen.
  
}

@defproc[(ws-send-evt [socket ws-socket?] [frame (or/c bytes? string?)]) evt?]{

  Returns a synchronizable event that becomes ready when data can be written to
  the WebSocket @scheme[socket], sends the given @scheme[frame] when chosen and
  returns a void value.
  
}

@defproc[(ws-receive [socket ws-socket?]) (or/c bytes? string? eof-object?)]{

  Receives a message through the WebSocket @scheme[socket]. The message returned
  will be a byte string for frames of type @scheme[128] and a string for frames of
  type @scheme[0]. Any other frame type causes an error.
  
  If the WebSocket connection is closed before @scheme[ws-receive] can read any
  data, the end of file object is returned instead.
  
}

@defproc[(ws-receive-ready-evt [socket ws-socket?]) evt?]{

  Returns a synchronizable event that becomes ready when data can be read from
  the WebSocket @scheme[socket] and returns the socket itself when chosen.
  
}

@defproc[(ws-receive-evt [socket ws-socket?]) evt?]{

  Returns a synchronizable event that becomes ready when data can be read from
  the WebSocket @scheme[socket] and returns the incoming frame or an end of file
  object when chosen.
  
}