infra-docs-fpo/modules/sysadmin_guide/pages/fedmsg-websocket.adoc

= websocket SOP

websocket communication with Fedora apps.

See-also: <<fedmsg-gateway.adoc#>>

== Contact Information

Owner::
  Messaging SIG, Fedora Infrastructure Team
Contact::
  #fedora-apps, #fedora-admin, #fedora-noc
Servers::
  busgateway01, proxy0*, app0*
Purpose::
  Expose a websocket server for FI apps to use

== Description

_WebSocket_ is a protocol (an extension of HTTP/1.1) by which client web
browsers can establish full-duplex socket communications with a server
--the "real-time web".

In our case, webapps served from _app0*_ and _packages0*_ will include
javascript code instructing client browsers to establish a second
connection to our _WebSocket_ server. They point browsers to the following
addresses:

production::
  wss://hub.fedoraproject.org:9939
staging::
  wss://stg.fedoraproject.org:9939

The websocket server itself is a _fedmsg-hub_ daemon running on
_busgateway01_. It is configured to enable its websocket server component
in the presence of certain configuration values.

_haproxy_ mediates connections to the _fedmsg-hub_ _websocket_ server daemon.
An _stunnel_ daemon provides SSL support.

== Connection Flow

The connection flow is much the same as in the <<fedmsg-gateway.adoc#>>,
but is somewhat more complicated.

"Normal" HTTP requests to our app servers traverse the following chain:

....
Client -> apache(proxy01) -> haproxy(proxy01) -> apache(app01)
....

The flow for a websocket requests looks something like this:

....
Client -> stunnel(proxy01) -> haproxy(proxy01) -> fedmsg-hub(busgateway01)
....

stunnel is listening on a public port, negotiates the SSL connection,
and redirects the connection to haproxy who in turn hands it off to the
_fedmsg-hub_ websocket server listening on _busgateway01_.

At the time of this writing, _haproxy_ does not actually load balance
zeromq session requests across multiple _busgateway0*_ machines, but there
is nothing stopping us from adding them. New hosts can be added in
ansible and pressed from _busgateway01_'s template. Add them to the
_fedmsg-websockets_ listen in _haproxy_'s config and it should Just Work.

== RHIT

We had RHIT open up port 9939 special to _proxy01.iad2_ for this.