html5/spec/eventsource Overview.html,NONE,1.1

Update of /sources/public/html5/spec/eventsource
In directory hutz:/tmp/cvs-serv4694/eventsource

Added Files:
	Overview.html 
Log Message:
Extract Web Sockets, Event Source, and Web Storage out of HTML5.

--- NEW FILE: Overview.html ---
<!DOCTYPE html><!-- when publishing, change bits marked ZZZ --><html lang=en-US-x-Hixie><meta charset=ascii><title>Server-Sent Events</title><style type=text/css>
   pre { margin-left: 2em; white-space: pre-wrap; }
   h2 { margin: 3em 0 1em 0; }
   h3 { margin: 2.5em 0 1em 0; }
   h4 { margin: 2.5em 0 0.75em 0; }
   h5, h6 { margin: 2.5em 0 1em; }
   h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
   h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
   p { margin: 1em 0; }
   hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
   dl, dd { margin-top: 0; margin-bottom: 0; }
   dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
   dt + dt { margin-top: 0; }
   dd dt { margin-top: 0.25em; margin-bottom: 0; }
   dd p { margin-top: 0; }
   dd dl + p { margin-top: 1em; }
   dd table + p { margin-top: 1em; }
   p + * > li, dd li { margin: 1em 0; }
   dt, dfn { font-weight: bold; font-style: normal; }
   dt dfn { font-style: italic; }
   pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
   pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
   pre em { font-weight: bolder; font-style: normal; }
   @media screen { code { color: orangered; } }
   var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
   table { border-collapse: collapse; border-style: hidden hidden none hidden; }
   table thead { border-bottom: solid; }
   table tbody th:first-child { border-left: solid; }
   table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
   blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }

   .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
   .matrix, .matrix td { border: none; text-align: right; }
   .matrix { margin-left: 2em; }
   .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
   .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
   .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
   .applies th > * { display: block; white-space: nowrap; }
   .applies thead code { display: block; }
   .applies td { text-align: center; }
   .applies .yes { background: yellow; }

   .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
   img.extra { float: right; }
   pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; }
   pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
   pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
   pre.css:first-line { color: #AAAA50; }
   dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #EEFFEE; }
   hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
   dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
   dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
   dl.domintro dd p { margin: 0.5em 0; }
   dl.switch { padding-left: 2em; }
   dl.switch > dt { text-indent: -1.5em; }
   dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
   .diff-old { text-decoration: line-through; color: silver; background: transparent; }
   .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
   a .diff-new { border-bottom: 1px blue solid; }

   h2 { page-break-before: always; }
   h1 + h2, hr + h2.no-toc { page-break-before: auto; }

   div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
   div.head p { margin: 0; }
   div.head h1 { margin: 0; }
   div.head .logo { float: right; margin: 0 1em; }
   div.head .logo img { border: none } /* remove border from top image */
   div.head dl { margin: 1em 0; }
   p.copyright { font-size: x-small; font-style: oblique; margin: 0; }

   body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
   body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
   body > .toc > li > * { margin-bottom: 0.5em; }
   body > .toc > li > * > li > * { margin-bottom: 0.25em; }
   .toc, .toc li { list-style: none; }

   .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
   .brief li { margin: 0; padding: 0; }
   .brief li p { margin: 0; padding: 0; }

   .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
   .XXX > :first-child { margin-top: 0; }
   p .XXX { line-height: 3em; }
   .note { color: green; background: transparent; font-family: sans-serif; }
   .warning { color: red; background: transparent; }
   .note, .warning { font-weight: bolder; font-style: italic; }
   p.note, div.note { padding: 0.5em 2em; }
   span.note { padding: 0 2em; }
   .note p:first-child, .warning p:first-child { margin-top: 0; }
   .note p:last-child, .warning p:last-child { margin-bottom: 0; }
   .warning:before { font-style: normal; }
   p.note:before { content: 'Note: '; }
   p.warning:before { content: '\26A0 Warning! '; }

   .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
   .bookkeeping { font-size: 0.8em; margin: 2em 0; }
   .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }

   h4 { position: relative; z-index: 3; }
   h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
   .element {
     background: #EEFFEE;
     color: black;
     margin: 0 0 1em 0.15em;
     padding: 0 1em 0.25em 0.75em;
     border-left: solid #99FF99 0.25em;
     position: relative;
     z-index: 1;
   }
   .element:before {
     position: absolute;
     z-index: 2;
     top: 0;
     left: -1.15em;
     height: 2em;
     width: 0.9em;
     background: #EEFFEE;
     content: ' ';
     border-style: none none solid solid;
     border-color: #99FF99;
     border-width: 0.25em;
   }

   .example {
     display: block;
     color: #222222;
     background: #FCFCFC;
     border-left: double;
     margin-left: 2em;
     padding-left: 1em;
   }

   .tall-and-narrow {
     font-size: 0.6em;
     column-width: 25em;
     column-gap: 1em;
     -moz-column-width: 25em;
     -moz-column-gap: 1em;
     -webkit-column-width: 25em;
     -webkit-column-gap: 1em;
   }
  </style><link href=http://www.w3.org/StyleSheets/TR/%57%33%43-ED rel=stylesheet type=text/css><!-- ZZZ ED vs WD --><div class=head>
   <p><a href=http://www.w3.org/><img alt=W3C height=48 src=http://www.w3.org/Icons/w3c_home width=72></a></p>
   <h1>Server-Sent Events</h1>
   <h2 class="no-num no-toc" id=editor-s-draft-date-zzz-9-june-2008><!-- "W3C Working Draft" --> Editor's Draft <!--ZZZ-->18 March 2009</h2>
   <dl><!-- ZZZ: update the month/day
    <dt>This Version:</dt>
    <dd><a href="http://www.w3.org/TR/2009/WD-eventsource-20090101/">http://www.w3.org/TR/2009/WD-eventsource-20090101/</a></dd>
    <dt>Latest Published Version:</dt>
    <dd><a href="http://www.w3.org/TR/eventsource/">http://www.w3.org/TR/eventsource/</a></dd>
 :ZZZ --><dt>Latest Editor's Draft:</dt>
    <dd><a href=http://dev.w3.org/html5/eventsource/>http://dev.w3.org/html5/eventsource/</a></dd>
<!-- ZZZ: add the new version after it has shipped
    <dt>Previous Versions:</dt>
    <dd><a href="http://www.w3.org/TR/2008/WD-eventsource-20080101/">http://www.w3.org/TR/2008/WD-eventsource-20080101/</a>
 :ZZZ -->
    <dt>Editors:</dt>
    <dd><a href=mailto:ian@hixie.ch>Ian Hickson</a>, Google, Inc.</dd>
   </dl><p class=copyright><a href=http://www.w3.org/Consortium/Legal/ipr-notice#Copyright>Copyright</a>
   &copy; 2008 <a href=http://www.w3.org/><abbr title="World Wide
   Web Consortium">W3C</abbr></a><sup>&reg;</sup> (<a href=http://www.csail.mit.edu/><abbr title="Massachusetts
   Institute of Technology">MIT</abbr></a>, <a href=http://www.ercim.org/><abbr title="European Research
   Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href=http://www.keio.ac.jp/>Keio</a>), All Rights Reserved. W3C
   <a href=http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer>liability</a>,
   <a href=http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks>trademark</a>
   and <a href=http://www.w3.org/Consortium/Legal/copyright-documents>document
   use</a> rules apply.</p>
  </div><hr class=top><h2 class="no-num no-toc" id=abstract>Abstract</h2><p>This specification defines an API for opening an HTTP connection
  for receiving push notifications from a server in the form of DOM
  events. The API is designed such that it can be extended to work
  with other push notification schemes such as Push SMS.<h2 class="no-num no-toc" id=status-of-this-document>Status of this document</h2><!-- intro boilerplate (required) --><p><em>This section describes the status of this document at the
  time of its publication. Other documents may supersede this
  document. A list of current W3C publications and the most recently
  formally published revision of this technical report can be found in
  the <a href=http://www.w3.org/TR/>W3C technical reports index</a>
  at http://www.w3.org/TR/.</em></p><!-- where to send feedback (required) --><p>If you wish to make comments regarding this document, please send
  them to <a href=mailto:public-webapps-comments@w3.org>public-webapps-comments@w3.org</a>
  (<a href="mailto:public-webapps-comments-request@w3.org?subject=subscribe">subscribe</a>,
  <a href=http://lists.w3.org/Archives/Public/public-webapps-comments/>archives</a>).
  All feedback is welcome.</p><!-- stability (required) --><p>Implementors should be aware that this specification is not
  stable. <strong>Implementors who are not taking part in the
  discussions are likely to find the specification changing out from
  under them in incompatible ways.</strong> Vendors interested in
  implementing this specification before it eventually reaches the
  Candidate Recommendation stage should join the aforementioned
  mailing lists and take part in the discussions.</p><!-- version history or list of changes (required) --><p>The latest stable version of the editor's draft of this
  specification is always available on <a href=http://dev.w3.org/html5/eventsource/Overview.html>the W3C CVS
  server</a>. Change tracking for this document is available at the
  following location:<ul><li>CVS log: <a href=http://dev.w3.org/cvsweb/html5/eventsource/Overview.html>http://dev.w3.org/cvsweb/html5/eventsource/Overview.html</a></li>
  </ul><!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- relationship to other work (required) --><p>This specification is automatically generated from the
  corresponding section in the HTML5 specification's source document,
  as hosted in the <a href=http://svn.whatwg.org/webapps/>WHATWG
  Subversion repository</a>. Detailed change history for all of HTML5,
  including the parts that form this specification, can be found at
  the following locations:</p><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING LIST TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><ul><li>Twitter messages (non-editorial changes only): <a href=http://twitter.com/WHATWG>http://twitter.com/WHATWG</a></li>
   <li>Interactive Web interface: <a href=http://html5.org/tools/web-apps-tracker>http://html5.org/tools/web-apps-tracker</a></li>
   <li>Commit-Watchers mailing list: <a href=http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org>http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org</a></li>
   <li>Subversion interface: <a href=http://svn.whatwg.org/webapps/>http://svn.whatwg.org/webapps/</a></li>
  </ul><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING LIST TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- status of document, group responsible (required) --><p>The W3C <a href=http://www.w3.org/2008/webapps/>Web Apps
  Working Group</a> is the W3C working group responsible for this
  specification's progress along the W3C Recommendation track.
  <!--ZZZ:-->
  This specification is the 18 March 2009 <!--ZZZ "Working Draft"-->Editor's Draft.
  <!--:ZZZ-->
  </p><!-- required patent boilerplate --><p>This document was produced by a group operating under the <a href=http://www.w3.org/Consortium/Patent-Policy-20040205/>5
  February 2004 W3C Patent Policy</a>. W3C maintains a <a href=http://www.w3.org/2004/01/pp-impl/42538/status rel=disclosure>public list of
  any patent disclosures</a> made in connection with the deliverables
  of the group; that page also includes instructions for disclosing a
  patent. An individual who has actual knowledge of a patent which the
  individual believes contains <a href=http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential>Essential
  Claim(s)</a> must disclose the information in accordance with <a href=http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure>section
  6 of the W3C Patent Policy</a>.<h2 class="no-num no-toc" id=contents>Table of contents</h2>
<!--begin-toc-->
<ol class=toc>
 <li><a href=#server-sent-events-intro><span class=secno>1 </span>Introduction</a></li>
 <li><a href=#conformance-requirements><span class=secno>2 </span>Conformance requirements</a>
  <ol>
   <li><a href=#dependencies><span class=secno>2.1 </span>Dependencies</a></ol></li>
 <li><a href=#terminology><span class=secno>3 </span>Terminology</a></li>
 <li><a href=#the-eventsource-interface><span class=secno>4 </span>The <code>EventSource</code> interface</a></li>
 <li><a href=#processing-model><span class=secno>5 </span>Processing model</a></li>
 <li><a href=#parsing-an-event-stream><span class=secno>6 </span>Parsing an event stream</a></li>
 <li><a href=#event-stream-interpretation><span class=secno>7 </span>Interpreting an event stream</a></li>
 <li><a href=#notes><span class=secno>8 </span>Notes</a></li>
 <li><a href=#garbage-collection><span class=secno>9 </span>Garbage collection</a></li>
 <li><a class=no-num href=#references>References</a></ol>
<!--end-toc--><hr><h2 id=server-sent-events-intro><span class=secno>1 </span>Introduction</h2><p><em>This section is non-normative.</em><p>To enable servers to push data to Web pages over HTTP or using
  dedicated server-push protocols, this specification introduces the
  <code><a href=#eventsource>EventSource</a></code> interface.<p class=XXX>An introduction to the client-side and
  server-side of using the direct connection APIs.<h2 id=conformance-requirements><span class=secno>2 </span>Conformance requirements</h2><p>All diagrams, examples, and notes in this specification are
  non-normative, as are all sections explicitly marked non-normative.
  Everything else in this specification is normative.<p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
  NOT",--> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
  "OPTIONAL" in the normative parts of this document are to be
  interpreted as described in RFC2119. For readability, these words do
  not appear in all uppercase letters in this specification. <a href=#refsRFC2119>[RFC2119]</a><p>Requirements phrased in the imperative as part of algorithms
  (such as "strip any leading space characters" or "return false and
  abort these steps") are to be interpreted with the meaning of the
  key word ("must", "should", "may", etc) used in introducing the
  algorithm.<p>Some conformance requirements are phrased as requirements on
  attributes, methods or objects. Such requirements are to be
  interpreted as requirements on user agents.<p>Conformance requirements phrased as algorithms or specific steps
  may be implemented in any manner, so long as the end result is
  equivalent. (In particular, the algorithms defined in this
  specification are intended to be easy to follow, and not intended to
  be performant.)<p>The only conformance class defined by this specification is user
  agents.<p>User agents may impose implementation-specific limits on
  otherwise unconstrained inputs, e.g. to prevent denial of service
  attacks, to guard against running out of memory, or to work around
  platform-specific limitations.<h3 id=dependencies><span class=secno>2.1 </span>Dependencies</h3><p>This specification relies on several other underlying
  specifications.<dl><dt>HTML5</dt>

   <dd>

    <p>Many fundamental concepts from HTML5 are used by this
    specification. <a href=#refsHTML5>[HTML5]</a></p>

   </dd>

   <dt>WebIDL</dt>

   <dd>

    <p>The IDL blocks in this specification use the semantics of the
    WebIDL specification. <a href=#refsWebIDL>[WebIDL]</a></p>

   </dd>

  </dl><h2 id=terminology><span class=secno>3 </span>Terminology</h2><p>The construction "a <code title="">Foo</code> object", where
  <code title="">Foo</code> is actually an interface, is sometimes
  used instead of the more accurate "an object implementing the
  interface <code title="">Foo</code>".<p>The term DOM is used to refer to the API set made available to
  scripts in Web applications, and does not necessarily imply the
  existence of an actual <code>Document</code> object or of any other
  <code>Node</code> objects as defined in the DOM Core
  specifications. <a href=#refsDOM3CORE>[DOM3CORE]</a><p>A DOM attribute is said to be <em>getting</em> when its value is
  being retrieved (e.g. by author script), and is said to be
  <em>setting</em> when a new value is assigned to it.<h2 id=the-eventsource-interface><span class=secno>4 </span>The <code><a href=#eventsource>EventSource</a></code> interface</h2><pre class=idl>[<a href=#dom-eventsource title=dom-EventSource>Constructor</a>(in DOMString url)]
interface <dfn id=eventsource>EventSource</dfn> {
  readonly attribute DOMString <a href=#dom-eventsource-url title=dom-EventSource-URL>URL</a>;

  // ready state
  const unsigned short <a href=#dom-eventsource-connecting title=dom-EventSource-CONNECTING>CONNECTING</a> = 0;
  const unsigned short <a href=#dom-eventsource-open title=dom-EventSource-OPEN>OPEN</a> = 1;
  const unsigned short <a href=#dom-eventsource-closed title=dom-EventSource-CLOSED>CLOSED</a> = 2;
  readonly attribute long <a href=#dom-eventsource-readystate title=dom-EventSource-readyState>readyState</a>;

  // networking
           attribute <span>Function</span> <a href=#handler-eventsource-onopen title=handler-EventSource-onopen>onopen</a>;
           attribute <span>Function</span> <a href=#handler-eventsource-onmessage title=handler-EventSource-onmessage>onmessage</a>;
           attribute <span>Function</span> <a href=#handler-eventsource-onerror title=handler-EventSource-onerror>onerror</a>;
  void <a href=#dom-eventsource-disconnect title=dom-EventSource-disconnect>disconnect</a>();
};</pre><p><code><a href=#eventsource>EventSource</a></code> objects must also implement the
  <code>EventTarget</code> interface. <a href=#refsDOM3EVENTS>[DOM3EVENTS]</a><p>The <dfn id=dom-eventsource title=dom-EventSource><code>EventSource(<var title="">url</var>)</code></dfn> constructor takes one argument,
  <var title="">url</var>, which specifies the <span>URL</span> to
  which to connect. When the <code>EventSource()</code> constructor is
  invoked, the UA must run these steps:<ol><li><p><span title="resolve a url">Resolve</span> the
   <span>URL</span> specified in <var title="">src</var>, relative to
   the <span>first script</span>'s <span title="script's base
   URL">base URL</span>.</li>

   <li><p>If the previous step failed, then throw a
   <code>SYNTAX_ERR</code> exception.</li>

   <li><p>Return a new <code><a href=#eventsource>EventSource</a></code> object, and continue
   these steps in the background (without blocking scripts).</li>

   <li><p><span>Fetch</span> the resource identified by the resulting
   <span>absolute URL</span>, as described below.</li>

  </ol><p>The <dfn id=dom-eventsource-url title=dom-EventSource-URL><code>URL</code></dfn>
  attribute must return the value that was passed to the
  constructor.<p>The <dfn id=dom-eventsource-readystate title=dom-EventSource-readyState><code>readyState</code></dfn>
  attribute represents the state of the connection. It can have the
  following values:<dl><dt><dfn id=dom-eventsource-connecting title=dom-EventSource-CONNECTING><code>CONNECTING</code></dfn> (numeric value 0)</dt>

   <dd>The connection has not yet been established, or it was closed
   and the user agent is reconnecting.</dd>

   <dt><dfn id=dom-eventsource-open title=dom-EventSource-OPEN><code>OPEN</code></dfn> (numeric value 1)</dt>

   <dd>The user agent has an open connection and is dispatching events
   as it receives them.</dd>

   <dt><dfn id=dom-eventsource-closed title=dom-EventSource-CLOSED><code>CLOSED</code></dfn> (numeric value 2)</dt>

   <dd>The connection is not open, and the user agent is not trying to
   reconnect. Either there was a fatal error or the <code title=dom-EventSource-disconnect><a href=#dom-eventsource-disconnect>disconnect()</a></code> method was
   invoked.</dd>

  </dl><p>When the object is created its <code title=dom-EventSource-readyState><a href=#dom-eventsource-readystate>readyState</a></code> must be set to
  <code title=dom-EventSource-CONNECTING><a href=#dom-eventsource-connecting>CONNECTING</a></code> (0). The
  rules given below for handling the connection define when the value
  changes.<p>The <dfn id=dom-eventsource-disconnect title=dom-EventSource-disconnect><code>disconnect()</code></dfn>
  method must close the connection, if any, and must set the <code title=dom-EventSource-readyState><a href=#dom-eventsource-readystate>readyState</a></code> attribute to
  <code title=dom-EventSource-CLOSED><a href=#dom-eventsource-closed>CLOSED</a></code>. If the
  connection is already closed, the method must do nothing.<p>The following are the <span>event handler attributes</span> that
  must be supported, as DOM attributes, by all objects implementing
  the <code><a href=#eventsource>EventSource</a></code> interface:<dl><dt><dfn id=handler-eventsource-onopen title=handler-EventSource-onopen><code>onopen</code></dfn></dt>

   <dd><p>Must be invoked whenever an <code title=event-open>open</code> event is targeted at or
   bubbles through the <code><a href=#eventsource>EventSource</a></code> object.</dd>

   <dt><dfn id=handler-eventsource-onmessage title=handler-EventSource-onmessage><code>onmessage</code></dfn></dt>

   <dd><p>Must be invoked whenever a <code title=event-message>message</code> event is targeted at or
   bubbles through the <code><a href=#eventsource>EventSource</a></code> object.</dd>

   <dt><dfn id=handler-eventsource-onerror title=handler-EventSource-onerror><code>onerror</code></dfn></dt>

   <dd><p>Must be invoked whenever an <code title=event-error>error</code> event is targeted at or
   bubbles through the <code><a href=#eventsource>EventSource</a></code> object.</dd>

  </dl><hr><p>In addition to the above, each <code><a href=#eventsource>EventSource</a></code> object
  has the following associated with it:<ul><li>A <dfn id=concept-event-stream-reconnection-time title=concept-event-stream-reconnection-time>reconnection
   time</dfn>, in milliseconds. This must initially be a
   user-agent-defined value, probably in the region of a few
   seconds.</li>

   <li>A <dfn id=concept-event-stream-last-event-id title=concept-event-stream-last-event-id>last event
   ID string</dfn>. This must initially be the empty string.</li>

  </ul><p>These values are not currently exposed on the interface.<h2 id=processing-model><span class=secno>5 </span>Processing model</h2><p>The resource indicated in the argument to the <code title=dom-EventSource><a href=#dom-eventsource>EventSource</a></code> constructor is <span title=fetch>fetched</span> when the constructor is run.<p>For HTTP connections, the <code title="">Accept</code> header may
  be included; if included, it must contain only formats of event
  framing that are supported by the user agent (one of which must be
  <code>text/event-stream</code>, as described below).<p>If the event source's last event ID string is not the empty
  string, then a <code title="">Last-Event-ID</code> HTTP header must
  be included with the request, whose value is the value of the event
  source's last event ID string.<p>User agents should use the <code>Cache-Control: no-cache</code>
  header in requests to bypass any caches for requests of event
  sources. User agents should ignore HTTP cache headers in the
  response, never caching event sources.<p class=XXX>Cross-origin loads are expected to follow the
  Access-Control semantics of CORS; without this header, they are
  expected to fail as if the site was down.<hr><p>As data is received, the <span title=concept-task>tasks</span>
  queued by the <span>networking task source</span> to handle the data
  must act as follows.<p>HTTP 200 OK responses with a <span>Content-Type</span> header
  specifying the type <code>text/event-stream</code> must be processed
  line by line <a href=#event-stream-interpretation>as described
  below</a>.<p>When a successful response with a supported MIME type is
  received, such that the user agent begins parsing the contents of
  the stream, the user agent must <a href=#announce-the-connection>announce the
  connection</a>.<p>If such a resource (with the correct MIME type) completes loading
  (i.e. the entire HTTP response body is received or the connection
  itself closes), the user agent must <a href=#reset-the-connection>reset the
  connection</a>. This doesn't apply for the error cases that are
  listed below.<p>HTTP 200 OK responses that have a <span>Content-Type</span> other
  than <code>text/event-stream</code> (or some other supported type)
  must cause the user agent to <a href=#fail-the-connection>fail the connection</a>.<p>HTTP 204 No Content, and 205 Reset Content responses are
  equivalent to 200 OK responses with the right MIME type but no
  content, and thus must <a href=#reset-the-connection>reset the connection</a>.<p>Other HTTP response codes in the 2xx range <!--201 Created, 202
  Accepted, 203 Non-Authoritative Information, and 206 Partial
  Content-->must similarly <a href=#reset-the-connection>reset the connection</a>. They
  are, however, likely to indicate an error has occurred somewhere and
  may cause the user agent to emit a warning.<p>HTTP 301 Moved Permanently responses must cause the user agent to
  reconnect using the new server specified URL instead of the
  previously specified URL for all subsequent requests for this event
  source. (It doesn't affect other <code><a href=#eventsource>EventSource</a></code> objects
  with the same URL unless they also receive 301 responses, and it
  doesn't affect future sessions, e.g. if the page is reloaded.)<p>HTTP 302 Found, 303 See Other, and 307 Temporary Redirect
  responses must cause the user agent to connect to the new
  server-specified URL, but if the user agent needs to again request
  the resource at a later point, it must return to the previously
  specified URL for this event source.<p>HTTP 305 Use Proxy, HTTP 401 Unauthorized, and 407 Proxy
  Authentication Required should be treated transparently as for any
  other subresource.<p>Any other HTTP response code not listed here or network error
  (e.g. DNS errors) must cause the user agent to <a href=#fail-the-connection>fail the
  connection</a>.</p><!-- including: HTTP 300 Multiple Choices,
  HTTP 304 Not Modified, HTTP 400 Bad Request, 403 Forbidden, 404 Not
  Found, 405 Method Not Allowed, 406 Not Acceptable, 408 Request
  Timeout, 409 Conflict, 410 Gone, 411 Length Required, 412
  Precondition Failed, 413 Request Entity Too Large, 414 Request-URI
  Too Long, 415 Unsupported Media Type, 416 Requested Range Not
  Satisfiable, 417 Expectation Failed, 500 Internal Server Error, 501
  Not Implemented, 502 Bad Gateway, 503 Service Unavailable, 504
  Gateway Timeout, and 505 HTTP Version Not Supported responses --><p>For non-HTTP protocols, UAs should act in equivalent ways.<hr><p>When a user agent is to <dfn id=announce-the-connection>announce the connection</dfn>, the
  user agent must set the <code title=dom-EventSource-readyState><a href=#dom-eventsource-readystate>readyState</a></code> attribute to
  <code title=dom-EventSource-OPEN><a href=#dom-eventsource-open>OPEN</a></code> and <span>queue a
  task</span> to <span>fire a simple event</span> named <code title=event-open>open</code> at the
  <code><a href=#eventsource>EventSource</a></code> object.<p>When a user agent is to <dfn id=reset-the-connection>reset the connection</dfn>, the user
  agent must set the <code title=dom-EventSource-readyState><a href=#dom-eventsource-readystate>readyState</a></code> attribute to
  <code title=dom-EventSource-CONNECTING><a href=#dom-eventsource-connecting>CONNECTING</a></code>,
  <span>queue a task</span> to <span>fire a simple event</span> named
  <code title=event-error>error</code> at the
  <code><a href=#eventsource>EventSource</a></code> object, and then <span>fetch</span> the
  event source resource again after a delay equal to the reconnection
  time of the event source. <strong>Only if the user agent <a href=#reset-the-connection title="reset the connection">resets the connection</a> does the
  connection get opened anew!</strong><p>When a user agent is to <dfn id=fail-the-connection>fail the connection</dfn>, the user
  agent must set the <code title=dom-EventSource-readyState><a href=#dom-eventsource-readystate>readyState</a></code> attribute to
  <code title=dom-EventSource-CLOSED><a href=#dom-eventsource-closed>CLOSED</a></code> and <span>queue a
  task</span> to <span>fire a simple event</span> named <code title=event-error>error</code> at the <code><a href=#eventsource>EventSource</a></code>
  object. <strong>Once the user agent has <a href=#fail-the-connection title="fail the
  connection">failed the connection</a>, it does <em>not</em>
  attempt to reconnect!</strong><hr><p>The <span>task source</span> for any <span title=concept-task>tasks</span> that are <span title="queue a
  task">queued</span> by <code><a href=#eventsource>EventSource</a></code> objects is the
  <dfn id=remote-event-task-source>remote event task source</dfn>.<h2 id=parsing-an-event-stream><span class=secno>6 </span>Parsing an event stream</h2><p>This event stream format's MIME type is
  <code>text/event-stream</code>.<p>The event stream format is as described by the <code title="">stream</code> production of the following ABNF, the
  character set for which is Unicode. <a href=#refsABNF>[ABNF]</a></p><!-- XXX
  ftp://ftp.rfc-editor.org/in-notes/std/std68.txt --><pre>stream        = [ bom ] *event
event         = *( comment / field ) end-of-line
comment       = colon *any-char end-of-line
field         = 1*name-char [ colon [ space ] *any-char ] end-of-line
end-of-line   = ( cr lf / cr / lf / eof )
eof           = &lt; matches repeatedly at the end of the stream &gt;

; characters
lf            = %x000A ; U+000A LINE FEED
cr            = %x000D ; U+000D CARRIAGE RETURN
space         = %x0020 ; U+0020 SPACE
colon         = %x003A ; U+003A COLON
bom           = %xFEFF ; U+FEFF BYTE ORDER MARK
name-char     = %x0000-0009 / %x000B-000C / %x000E-0039 / %x003B-10FFFF
                ; a Unicode character other than U+000A LINE FEED, U+000D CARRIAGE RETURN, or U+003A COLON
any-char      = %x0000-0009 / %x000B-000C / %x000E-10FFFF
                ; a Unicode character other than U+000D CARRIAGE RETURN or U+003A COLON</pre><p>Event streams in this format must always be encoded as
  UTF-8.<p>Lines must be separated by either a U+000D CARRIAGE RETURN U+000A
  LINE FEED (CRLF) character pair, a single U+000A LINE FEED (LF)
  character, or a single U+000D CARRIAGE RETURN (CR) character.<p>Since connections established to remote servers for such
  resources are expected to be long-lived, UAs should ensure that
  appropriate buffering is used. In particular, while line buffering
  with lines are defined to end with a single U+000A LINE FEED
  character is safe, block buffering or line buffering with different
  expected line endings can cause delays in event dispatch.<h2 id=event-stream-interpretation><span class=secno>7 </span>Interpreting an event stream</h2><p>Bytes or sequences of bytes that are not valid UTF-8 sequences
  must be interpreted as the U+FFFD REPLACEMENT CHARACTER.<p>One leading U+FEFF BYTE ORDER MARK character must be ignored if
  any are present.<p>The stream must then be parsed by reading everything line by
  line, with a U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF)
  character pair, a single U+000A LINE FEED (LF) character, a single
  U+000D CARRIAGE RETURN (CR) character, and the end of the file being
  the four ways in which a line can end.<p>When a stream is parsed, a <var title="">data</var> buffer and an
  <var title="">event name</var> buffer must be associated with
  it. They must be initialized to the empty string<p>Lines must be processed, in the order they are received, as
  follows:<dl class=switch><dt>If the line is empty (a blank line)</dt>

   <dd><p><a href=#dispatchMessage>Dispatch the event</a>, as
   defined below.</dd>


   <dt>If the line starts with a U+003A COLON character (':')</dt>

   <dd><p>Ignore the line.</dd>


   <dt>If the line contains a U+003A COLON character (':') character</dt>

   <dd>

    <p>Collect the characters on the line before the first U+003A
    COLON character (':'), and let <var title="">field</var> be that
    string.</p>

    <p>Collect the characters on the line after the first U+003A COLON
    character (':'), and let <var title="">value</var> be that
    string. If <var title="">value</var> starts with a single U+0020
    SPACE character, remove it from <var title="">value</var>.</p>

    <p><a href=#processField>Process the field</a> using the steps
    described below, using <var title="">field</var> as the field name
    and <var title="">value</var> as the field value.</p>

   </dd>


   <dt>Otherwise, the string is not empty but does not contain a U+003A COLON character (':') character</dt>

   <dd>

    <p><a href=#processField>Process the field</a> using the steps
    described below, using the whole line as the field name, and
    the empty string as the field value.</p>

   </dd>

  </dl><p>Once the end of the file is reached, the user agent must <a href=#dispatchMessage>dispatch the event</a> one final time, as
  defined below.<p id=processField>The steps to <dfn title="">process the
  field</dfn> given a field name and a field value depend on the field
  name, as given in the following list. Field names must be compared
  literally, with no case folding performed.<dl class=switch><dt>If the field name is "event"</dt>

   <dd><p>Set the <var title="">event name</var> buffer the to field
   value.</dd>


   <dt>If the field name is "data"</dt>

   <dd><p>If the <var title="">data</var> buffer is not the empty
   string, then append a single U+000A LINE FEED character to the <var title="">data</var> buffer. Append the field value to the <var title="">data</var> buffer.</dd>


   <dt>If the field name is "id"</dt>

   <dd><p>Set the event stream's <a href=#concept-event-stream-last-event-id title=concept-event-stream-last-event-id>last event ID</a> to
   the field value.</dd>


   <dt>If the field name is "retry"</dt>

   <dd><p>If the field value consists of only characters in the range
   U+0030 DIGIT ZERO ('0') U+0039 DIGIT NINE ('9'), then interpret the
   field value as an integer in base ten, and set the event stream's
   <a href=#concept-event-stream-reconnection-time title=concept-event-stream-reconnection-time>reconnection
   time</a> to that integer. Otherwise, ignore the field.</dd>

<!-- v2 feature request from John Fallows - http://www.w3.org/mid/c5b3a7130810271238h11e40a4fybfcd5983ed5dc08d@mail.gmail.com

   <dt>If the field name is "reconnect"</dt>

   <dd><p>If the field value is the empty string, then: <a
   href="#dispatchMessage">dispatch the event</a> as defined below,
   and then drop the connection and immediately reconnect as if the
   <span title="concept-event-stream-reconnection-time">reconnection
   time</span> was zero for this one time.</p></dd>

  -->

   <dt>Otherwise</dt>

   <dd><p>The field is ignored.</dd>

  </dl><p id=dispatchMessage>When the user agent is required to <dfn title="">dispatch the event</dfn>, then the user agent must act as
  follows:

  <ol><li><p>If the <var title="">data</var> buffer is an empty string,
   set the <var title="">data</var> buffer and the <var title="">event
   name</var> buffer to the empty string and abort these
   steps.</li>

   <li><p>If the <var title="">event name</var> buffer is not the
   empty string but is also not a valid <a href=http://www.w3.org/TR/REC-xml-names/#NT-NCName>NCName</a>,
   set the <var title="">data</var> buffer and the <var title="">event
   name</var> buffer to the empty string and abort these
   steps.</li>

   <li><p>Otherwise, create an event that uses the
   <code>MessageEvent</code> interface, with the event name <code title=event-message>message</code>, which does not bubble, is
   cancelable, and has no default action. The <code title=dom-MessageEvent-data>data</code> attribute must be set to
   the value of the <var title="">data</var> buffer, the <code title=dom-MessageEvent-origin>origin</code> attribute must be set
   to the <span title="Unicode serialization of an origin">Unicode
   serialization</span> of the <span>origin</span> of the event
   stream's URL, and the <code title=dom-MessageEvent-lastEventId>lastEventId</code> attribute
   must be set to the <span>last event ID string</span> of the event
   source.</li>
   
   <li><p>If the <var title="">event name</var> buffer has a value
   other than the empty string, change the type of the newly created
   event to equal the value of the <var title="">event name</var>
   buffer.</li>

   <li><p>Set the <var title="">data</var> buffer and the <var title="">event name</var> buffer to the empty string.</li>

   <li><p><span>Queue a task</span> to dispatch the newly created
   event at the <code><a href=#eventsource>EventSource</a></code> object.</li>

  </ol><p class=note>If an event doesn't have an "id" field, but an
  earlier event did set the event source's <span>last event ID
  string</span>, then the event's <code title=dom-MessageEvent-lastEventId>lastEventId</code> field will
  be set to the value of whatever the last seen "id" field was.<div class=example>

   <p>The following event stream, once followed by a blank line:</p>
   <pre>data: YHOO
data: +2
data: 10</pre>

   <p>...would cause an event <code title=event-message>message</code> with the interface
   <code>MessageEvent</code> to be dispatched on the
   <code><a href=#eventsource>EventSource</a></code> object. The event's <code title=dom-MessageEvent-data>data</code> attribute would contain
   the string <code>YHOO\n+2\n10</code> (where <code>\n</code>
   represents a newline).</p>

   <p>This could be used as follows:
   <pre>var stocks = new EventSource("http://stocks.example.com/ticker.php");
stocks.onmessage = function (event) {
  var data = event.data.split('\n');
  updateStocks(data[0], data[1], data[2]);
};</pre>

   <p>...where <code title="">updateStocks()</code> is a function defined as:</p>

   <pre>function updateStocks(symbol, delta, value) { ... }</pre>

   <p>...or some such.</p>

  </div><div class=example>

   <p>The following stream contains four blocks. The first block has
   just a comment, and will fire nothing. The second block has two
   fields with names "data" and "id" respectively; an event will be
   fired for this block, with the data "first event", and will then
   set the last event ID to "1" so that if the connection died between
   this block and the next, the server would be sent a <code title="">Last-Event-ID</code> header with the value "1". The third
   block fires an event with data "second event", and also has an "id"
   field, this time with no value, which resets the last event ID to
   the empty string (meaning no <code title="">Last-Event-ID</code>
   header will now be sent in the event of a reconnection being
   attempted). Finally the last block just fires an event with the
   data "third event". Note that the last block doesn't have to end
   with a blank line, the end of the stream is enough to trigger the
   dispatch of the last event.</p>

   <pre>: test stream

data: first event
id: 1

data: second event
id

data: third event</pre>
  </div><div class=example>

   <p>The following stream fires just one event:</p>

   <pre>data

data
data

data:</pre>

   <p>The first and last blocks do nothing, since they do not contain
   any actual data (the <var title="">data</var> buffer remains at the
   empty string, and so nothing gets dispatched). The middle block
   fires an event with the data set to a single newline character.</p>
  </div><div class=example>

   <p>The following stream fires two identical events:</p>

   <pre>data:test

data:&nbsp;test</pre>

   <p>This is because the space after the colon is ignored if
   present.</p>

  </div><h2 id=notes><span class=secno>8 </span>Notes</h2><p>Legacy proxy servers are known to, in certain cases, drop HTTP
  connections after a short timeout. To protect against such proxy
  servers, authors can include a comment line (one starting with a ':'
  character) every 15 seconds or so.<p>Authors wishing to relate event source connections to each other
  or to specific documents previously served might find that relying
  on IP addresses doesn't work, as individual clients can have
  multiple IP addresses (due to having multiple proxy servers) and
  individual IP addresses can have multiple clients (due to sharing a
  proxy server). It is better to include a unique identifier in the
  document when it is served and then pass that identifier as part of
  the URL in the <code title=attr-eventsource-src>src</code>
  attribute of the <code><a href=#eventsource>eventsource</a></code> element.<p>Authors are also cautioned that HTTP chunking can have unexpected
  negative effects on the reliability of this protocol. Where
  possible, chunking should be disabled for serving event streams
  unless the rate of messages is high enough for this not to
  matter.</p><!-- v2 can we get a better solution? --><p>Implementations that support HTTP's per-server connection
  limitation might run into trouble when opening multiple pages from a
  site if each page has an <code><a href=#eventsource>EventSource</a></code> to the same
  domain. Authors can avoid this using the relatively complex
  mechanism of using unique domain names per connection, or by
  allowing the user to enable or disable the <code><a href=#eventsource>EventSource</a></code>
  functionality on a per-page basis.<hr><p>Other formats of event framing may also be supported in addition
  to <code>text/event-stream</code>, but this specification does not
  define how they are to be parsed or processed.<p class=note>Such formats could include systems like SMS-push;
  for example servers could use <code title="">Accept</code> headers
  and HTTP redirects to an SMS-push mechanism as a kind of protocol
  negotiation to reduce network load in GSM environments.<h2 id=garbage-collection><span class=secno>9 </span>Garbage collection</h2><p>An <code><a href=#eventsource>EventSource</a></code> object with an open connection must not
  be garbage collected if there are any event listeners registered for
  <code title=event-message>message</code> events.<p>If an <code><a href=#eventsource>EventSource</a></code> object is garbage collected while
  its connection is still open, the connection must be closed.<h2 class=no-num id=references>References</h2><p class=big-issue>This section will be written in a future
  draft.<!--XXX-->

Received on Wednesday, 18 March 2009 19:35:52 UTC