Subject: [hybi] Requirements.

From: Greg Wilkins <[email-masked]>
Date: Mon, 01 Feb 2010 11:06:37 +1100

All, in line with the charter milestones,  I'd like to start a discussion
in preparation to preparing a requirements document for April.

In addition to the base/obvious requirements, I'd like to propose the
following requirements for *discussion* and *possible* inclusion in that
document.

Mote the intentional different usage of websocket endpoint and websocket
application.    This is mostly a summary list and more details and use-cases
are needed for each of the points.  However as many are inter-dependent, it
is worthwhile starting with a summary list.

Idle Timeout negotiation
========================
During websocket establishment, it should be possible for both endpoints
and any intermediary to communicate the maximum time they are prepared to
keep open an idle connection.

Intermediaries may participate in the timeout negotiation or simply observe
and respect the value negotiated.

Max message size
================
Endpoints should be able to declare the maximal message size that they
are prepared to accept.

Applications may be able to declare the maximal message size that they
will send.

Connection limits
=================
Connections can consume significant resources on a network and/or
server.  If a application has an unconstrained ability to open new
connections than an client may attempt to open more connections
as a way to reserve more of a servers resources for their application.
Unconstrained connection creation may also be used as a DOS attack
(although this is somewhat limited by the current requirement that only
a single handshake can be outstanding at once).

Endpoints (not applications) should enforce reasonable connection limits.
Endpoint implementations should be able to negotiate and/or declare
the maximal connection limits that they will enforce.

Orderly Close.
==============
That either endpoint or any intermediary may initiate an orderly close of
a websocket connection, such that any message sent before the close would
be guaranteed of delivery if there are no other failures of the connection.

Websocket endpoints and intermediaries would be able to distinguish between
an orderly close and a failure of a websocket and thus take different
application actions with regards to any non-idempotent messages recently
sent.

A websocket application that detects a non orderly close may choose to
retransmit recent messages on a new connection, warn the user that
some actions may not have been communicated or query the endpoint
on a new connection about the actual status.

A websocket endpoint that frequently detects non orderly closes on a
particular path may make statistical/heuristic inferences about the
ws support of intermediaries.  It may then take action by reducing idle
times and/or sending keep-alives.

Error Close
===========
If a protocol or resource error is detected (eg message size too large),
then a ws connection should be able to be closed in a way so that the
other endpoint can determine that the close was not due to network
failure and thus not try to resend the message.

Acknowledged Flush
==================
Either endpoint may initiate an acknowledged flush of a websocket connection.
This would be similar to an orderly close in that endpoints and intermediaries
would be able to know that all messages sent prior to the flush had been
delivered to the opposite endpoint, except that the connection would be
left open.

Acknowledged flush should be provided so that an application does not
use orderly close in order to achieve guaranteed message delivery.

Keep-alive messages
===================
Websocket applications may wish to maintain a websocket connection
even though it is currently idle.    For example, the existence of
a websocket connection may be used to indicate presence in a chat system.

In order to maintain an open ws connection, the application may choose
to send keepalive messages.  However, without communicating details
of the transport timeouts to the application, these keep alive messages
are likely to be more frequent than necessary.

It should be possible for a websocket endpoint to determine the desired
connectivity state of an application, and to send transparent keep-alive
messages so that any known or inferred idle timeouts can be avoided.

Content Type & encodings
========================

Websocket endpoints may wish to send data in alternative encodings
and with indications of content type.  Examples include compressing,
signing or encrypting messages, using utf-16 instead of utf-8 for
some language groups, sending images or other media.   Content type
and encoding is needed to make usage of the binary framing transport.

It's unclear if content type should be negotiated or simply declared.
The under utilization of accept- headers in HTTP would suggest negotiation
is perhaps not required.

It's unclear if Content type should be declared for an entire
channel, for inbound/outbound channels or message by message.

A use-case for message by message content type is sending images,
which may be one of a number of content types.     The argument
against message by message content type is verbosity and complexity.

Message Fragmentation
=====================
[this heading is more of a solution than a requirement... so looking
for a better name]

Currently it is possible for the sending of a large message to delay
the delivery of small messages sent subsequently.     It may be
a requirement that large messages be fragmented, so that smaller
messages can be delivered.   Or it may be a requirement that strict
message ordering is maintained.

Connection sharing
==================
If a connection limit is reached, it may be desirable to multiplex
multiple application endpoints onto a shared connection.   This may
avoid failure when multiple tabs, windows, widgets inadvertently
exceed a connection limit.

Intermediaries may offer connection aggregation services to reduce
the load on applications servers.

Standardized Extensions
=======================

Features/requirements that deemed to not be base requirements
(eg possibly message fragmentation and connection sharing), may
be desirable to support in the form of standardized extensions
to the protocol.

Standardized extensions will need to be implemented in the endpoint
and not in the application, so that they may be activated below
the standard APIs, transparently to the application.   For example,
an application written against the websocket API, should not need to
know that it's connection is being shared, compressed etc.

The protocol needs a standard way to declare and/or negotiate
the usage of or requirement for extensions.

regards