raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

!htc,doc,htp #19508 fix casing of WebSocket (as per spec)

Browse source
This commit is contained in:
Konrad Malawski 2016-01-19 20:43:59 +01:00
parent 0dd889aa17
commit 1b47fbeac7
72 changed files with 698 additions and 501 deletions
Download patch file Download diff file Expand all files Collapse all files

44
akka-docs/rst/java/http/server-side/websocket-support.rst
View file

@ -52,20 +52,20 @@ a streaming message from an Akka Stream source.
Server API
----------
The entrypoint for the Websocket API is the synthetic ``UpgradeToWebsocket`` header which is added to a request
if Akka HTTP encounters a Websocket upgrade request.
The entrypoint for the WebSocket API is the synthetic ``UpgradeToWebSocket`` header which is added to a request
if Akka HTTP encounters a WebSocket upgrade request.
The Websocket specification mandates that details of the Websocket connection are negotiated by placing special-purpose
The WebSocket specification mandates that details of the WebSocket connection are negotiated by placing special-purpose
HTTP-headers into request and response of the HTTP upgrade. In Akka HTTP these HTTP-level details of the WebSocket
handshake are hidden from the application and don't need to be managed manually.
Instead, the synthetic ``UpgradeToWebsocket`` represents a valid Websocket upgrade request. An application can detect
a Websocket upgrade request by looking for the ``UpgradeToWebsocket`` header. It can choose to accept the upgrade and
start a Websocket connection by responding to that request with an ``HttpResponse`` generated by one of the
``UpgradeToWebsocket.handleMessagesWith`` methods. In its most general form this method expects two arguments:
first, a handler ``Flow<Message, Message, ?>`` that will be used to handle Websocket messages on this connection.
Instead, the synthetic ``UpgradeToWebSocket`` represents a valid WebSocket upgrade request. An application can detect
a WebSocket upgrade request by looking for the ``UpgradeToWebSocket`` header. It can choose to accept the upgrade and
start a WebSocket connection by responding to that request with an ``HttpResponse`` generated by one of the
``UpgradeToWebSocket.handleMessagesWith`` methods. In its most general form this method expects two arguments:
first, a handler ``Flow<Message, Message, ?>`` that will be used to handle WebSocket messages on this connection.
Second, the application can optionally choose one of the proposed application-level sub-protocols by inspecting the
values of ``UpgradeToWebsocket.getRequestedProtocols`` and pass the chosen protocol value to ``handleMessagesWith``.
values of ``UpgradeToWebSocket.getRequestedProtocols`` and pass the chosen protocol value to ``handleMessagesWith``.
Handling Messages
+++++++++++++++++
@ -76,7 +76,7 @@ scenarios this fits very well and such a ``Flow`` can be constructed from a simp
There are other use-cases, e.g. in a server-push model, where a server message is sent spontaneously, or in a
true bi-directional scenario where input and output aren't logically connected. Providing the handler as a ``Flow`` in
these cases may not fit. An overload of ``UpgradeToWebsocket.handleMessagesWith`` is provided, instead,
these cases may not fit. An overload of ``UpgradeToWebSocket.handleMessagesWith`` is provided, instead,
which allows to pass an output-generating ``Source<Message, ?>`` and an input-receiving ``Sink<Message, ?>`` independently.
Note that a handler is required to consume the data stream of each message to make place for new messages. Otherwise,
@ -87,40 +87,40 @@ Example
Let's look at an example_.
Websocket requests come in like any other requests. In the example, requests to ``/greeter`` are expected to be
Websocket requests:
WebSocket requests come in like any other requests. In the example, requests to ``/greeter`` are expected to be
WebSocket requests:
.. includecode:: ../../code/docs/http/javadsl/server/WebsocketCoreExample.java
.. includecode:: ../../code/docs/http/javadsl/server/WebSocketCoreExample.java
:include: websocket-handling
It uses a helper method ``akka.http.javadsl.model.ws.Websocket.handleWebsocketRequestWith`` which can be used if
only Websocket requests are expected. The method looks for the ``UpgradeToWebsocket`` header and returns a response
that will install the passed Websocket handler if the header is found. If the request is no Websocket request it will
It uses a helper method ``akka.http.javadsl.model.ws.WebSocket.handleWebSocketRequestWith`` which can be used if
only WebSocket requests are expected. The method looks for the ``UpgradeToWebSocket`` header and returns a response
that will install the passed WebSocket handler if the header is found. If the request is no WebSocket request it will
return a ``400 Bad Request`` error response.
In the example, the passed handler expects text messages where each message is expected to contain (a person's) name
and then responds with another text message that contains a greeting:
.. includecode:: ../../code/docs/http/javadsl/server/WebsocketCoreExample.java
.. includecode:: ../../code/docs/http/javadsl/server/WebSocketCoreExample.java
:include: websocket-handler
Routing support
---------------
The routing DSL provides the ``handleWebsocketMessages`` directive to install a WebSocket handler if a request
The routing DSL provides the ``handleWebSocketMessages`` directive to install a WebSocket handler if a request
is a WebSocket request. Otherwise, the directive rejects the request.
Let's look at how the above example can be rewritten using the high-level routing DSL.
Instead of writing the request handler manually, the routing behavior of the app is defined by a route that
uses the ``handleWebsocketRequests`` directive in place of the ``Websocket.handleWebsocketRequestWith``:
uses the ``handleWebSocketRequests`` directive in place of the ``WebSocket.handleWebSocketRequestWith``:
.. includecode:: ../../code/docs/http/javadsl/server/WebsocketRoutingExample.java
.. includecode:: ../../code/docs/http/javadsl/server/WebSocketRoutingExample.java
:include: websocket-route
The handling code itself will be the same as with using the low-level API.
See the `full routing example`_.
.. _example: @github@/akka-docs-dev/rst/java/code/docs/http/javadsl/server/WebsocketCoreExample.java
.. _full routing example: @github@/akka-docs-dev/rst/java/code/docs/http/javadsl/server/WebsocketRoutingExample.java
.. _example: @github@/akka-docs-dev/rst/java/code/docs/http/javadsl/server/WebSocketCoreExample.java
.. _full routing example: @github@/akka-docs-dev/rst/java/code/docs/http/javadsl/server/WebSocketRoutingExample.java