Web sockets make it cheaper to talk to your servers.
Connecting to a server takes some time, so with web sockets, you make that connection once and then keep using. The major benefits of this are:
It faster to send messages. No need to do a bunch of work for every single message.
The server can push messages to you. With normal HTTP you would have to keep asking for changes, but a web socket, the server can talk to you whenever it wants. This means there is less unnecessary network traffic.
Internal state of the WebSocketClient module.
Get the initial, empty state with initialState
.
InternalMessage
Opaque message type.
You can create the instances you need to send with openMessage
, sendMessage
, closeMessage
, and bytesQueuedMessage
.
A response that your code must process to update your model.
NoResponse
means there's nothing to do.
CmdResponse
encapsulates a Message
that needs to be sent out through your Cmd
port. This is done internally. Your application code may ignore these responses.
ListResponse
contains a number of responses. It is generated only when you send messages while the connection is down, causing them to be queued up. It may contain one or more ReconnectedResponse
instances, so if you care about that, you should call reconnectedResponses
to extract them.
ConnectedResponse
tells you that an earlier call to send
or keepAlive
has successfully connected. You can usually ignore this.
ReconnectedResponse
is sent when the connection to the server has been re-established after being lost. If you need to re-establish logical connections after losing the physical connection, you'll need to pay attention to this. Otherwise, you can safely ignore it.
MessageReceivedResponse
is a message from one of the connected sockets.
ClosedResponse
tells you that an earlier call to close
has completed. Its code
, reason
, and wasClean
fields are as passed by the JavaScript WebSocket
interface. Its expected
field will be True
, if the response is to a close
call on your part. It will be False
if the close was unexpected, and reconnection attempts failed for 20 seconds (using exponential backoff between attempts).
ErrorResponse
means that something went wrong. Details in the encapsulated Error
.
All the errors that can be returned in a Response.ErrorResponse.
If an error tag has a single String
arg, that string is a socket key
.
This will usually be NormalClosure
. The rest are standard, except for UnknownClosure
, which denotes a code that is not defined, and TimeoutOutOnReconnect
, which means that exponential backoff connection reestablishment attempts timed out.
The standard codes are from https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent
{ v4_1 : () }
This is used to force a major version bump when the JS changes.
You'll usually not use it for anything.
PortFunnel.FunnelSpec
moduleName : String
The name of this module: "WebSocket".
moduleDesc : PortFunnel.ModuleDesc Message State Response
Our module descriptor.
commander : (PortFunnel.GenericMessage -> Platform.Cmd.Cmd msg) -> Response -> Platform.Cmd.Cmd msg
Responsible for sending a CmdResponse
back through the port.
Called by PortFunnel.appProcess
for each response returned by process
.
State
initialState : State
The initial, empty state.
Message
makeOpen : String -> Message
Create a Message
to open a connection to a WebSocket server.
makeOpen url
Example:
makeOpen "wss://echo.websocket.org"
|> send cmdPort
makeSend : String -> String -> Message
Create a Message
to send a string to a particular address.
makeSend key message
Example:
makeSend "wss://echo.websocket.org" "Hello!"
|> send cmdPort
You must send a makeOpen
or makeOpenWithKey
message before makeSend
.
If you send a makeSend
message before the connection has been established, or while it is being reestablished after it was lost, your message will be buffered and sent after the connection has been (re)established.
makeClose : String -> Message
Create a Message
to close a previously opened WebSocket.
makeClose key
The key
arg is either they key
arg to makeOpenWithKey
or
makeKeepAliveWithKey
or the url
arg to makeOpen
or makeKeepAlive
.
Example:
makeClose "echo"
|> send cmdPort
makeOpenWithKey : String -> String -> Message
Like makeOpen
, but allows matching a unique key to the connection.
makeOpen
uses the url as the key.
makeOpenWithKey key url
Example:
makeOpenWithKey "echo" "wss://echo.websocket.org"
makeKeepAlive : String -> Message
Create a Message
to connect to a WebSocket server, but not report received messages.
makeKeepAlive url
For keeping a connection open for when you only need to send makeSend
messages.
Example:
makeKeepAlive "wss://echo.websocket.org"
|> send cmdPort
makeKeepAliveWithKey : String -> String -> Message
Like makeKeepAlive
, but allows matching a unique key to the connection.
makeKeepAliveWithKey key url
Example:
makeKeepAliveWithKey "echo" "wss://echo.websocket.org"
|> send cmdPort
Message
out the Cmd
Portsend : (Json.Encode.Value -> Platform.Cmd.Cmd msg) -> Message -> Platform.Cmd.Cmd msg
Send a Message
through a Cmd
port.
toString : Message -> String
Convert a Message
to a nice-looking human-readable string.
toJsonString : Message -> String
Convert a Message
to the same JSON string that gets sent
over the wire to the JS code.
errorToString : Error -> String
Convert an Error
to a string, for simple reporting.
closedCodeToString : ClosedCode -> String
Turn a ClosedCode
into a String
, for debugging.
makeSimulatedCmdPort : (Json.Encode.Value -> msg) -> Json.Encode.Value -> Platform.Cmd.Cmd msg
Make a simulated Cmd
port.
isLoaded : State -> Basics.Bool
Returns true if a Startup
message has been processed.
This is sent by the port code after it has initialized.
isConnected : String -> State -> Basics.Bool
Returns true if a connection is open for the given key.
isConnected key state
getKeyUrl : String -> State -> Maybe String
Get the URL for a key.
willAutoReopen : String -> State -> Basics.Bool
Return True
if the connection for the given key will be automatically reopened if it closes unexpectedly.
This is the default. You may change it with setAutoReopen.
willAutoReopen key state
setAutoReopen : String -> Basics.Bool -> State -> State
Set whether the connection for the given key will be automatically reopened if it closes unexpectedly.
This defaults to True
. If you would rather get a ClosedResponse
when it happens and handle it yourself, set it to False
before sending a makeOpen
message.
You may change it back to False
later. Changing it to True
later will not interrupt any ongoing reconnection process.
setAutoReopen key autoReopen
The key is either the key you plan to use for a makeOpenWithKey
or makeKeepAliveWithKey
message or the url for a makeOpen
or makeKeepAlive
message.
filterResponses : (Response -> Basics.Bool) -> Response -> List Response
Filter the Response
arg with the predicate arg.
If the Response
is a ListResponse
, then return the elements of its
encapsulated list which satisfy the predicate.
If the Response
itself satisfies the predicate, return it in a single-element list.
Otherwise, return the empty list.
isReconnectedResponse : Response -> Basics.Bool
Return True
iff the Response
is a ReconnectedResponse
.
reconnectedResponses : Response -> List Response
Return a list of the ReconnectedResponse
instances in the Response
.
reconnectedResponses response
is equivalent to:
filterResponse isReconnectedResponse response
encode : Message -> PortFunnel.GenericMessage
Encode a Message
into a GenericMessage
.
Only exposed so the tests can use it.
User code will use it implicitly through moduleDesc
.
decode : PortFunnel.GenericMessage -> Result String Message
Decode a GenericMessage
into a Message
.
Only exposed so the tests can use it.
User code will use it implicitly through moduleDesc
.