Server-Sent Events（翻译）

原文：http://www.w3.org/TR/eventsource/　　

　　该文档是w3c标准push机制的翻译。

摘要

　　该规范定义了一套API，它开启一个HTTP连接，以DOM事件的形式收到从服务器端发来的通知。设计这个API的目的是它能够被扩展，使其能和其他push通知机制一起工作，就像Push SMS一样。

1、介绍

　　该文档是非规范的。

　　该规范介绍了EventSource接口，它使服务器能够通过HTTP或者专用的server-push协议来讲数据push到网页端。

　　用这个API创建一个EventSource对象，注册一个事件监听。

　　

var source = new EventSource('updates.cgi');
source.onmessage = function (event) {
  alert(event.data);
};

　　在服务器端，脚本（在这个例子中是updates.cgi）用下面的形式来发送消息，用text/event-stream MIME类型：

data: This is the first message.

data: This is the second message, it
data: has two lines.

data: This is the third message.

 　　作者能够通过不同的事件类型将事件分开。下面是有两种事件类型的流，add和remove：

event: add
data: 73857293

event: remove
data: 2153

event: add
data: 113411

　　处理这样的流，脚本需要这样写：

var source = new EventSource('updates.cgi');
source.addEventListener('add', addHandler, false);
source.addEventListener('remove', removeHandler, false);

　　其中，addHandler和removeHandler是带一个参数的函数。

　　缺省的事件类型是message。

　　用HTTP正常的请求，HTTP301和307重定向请求，事件流可以被重定向。如果连接关闭，客户端会重连接；通过HTTP204没有内容回应代码，客户端能被告知停止重连接。

　　用这个API而不是用XMLHttpRequest或者一个iframe来模拟它，能够允许用户代理更好地利用网络资源，在很多情况下，用户代理实现和网络操作是同等优先的。这个能够很好滴节省移动设备的电源。这个将在下面的无连接(connectionless) push一章还会被讨论。

2、术语

　　构造一个Foo对象，Foo实际上是一个接口，更准确滴说，是一个对象实现了Foo接口。

　　术语DOM

3、EventSource接口

[Constructor(DOMString url, optional EventSourceInit eventSourceInitDict)]
interface EventSource : EventTarget {
  readonly attribute DOMString url;
  readonly attribute boolean withCredentials;

  // ready state
  const unsigned short CONNECTING = 0;
  const unsigned short OPEN = 1;
  const unsigned short CLOSED = 2;
  readonly attribute unsigned short readyState;

  // networking
  [TreatNonCallableAsNull] attribute Function? onopen;
  [TreatNonCallableAsNull] attribute Function? onmessage;
  [TreatNonCallableAsNull] attribute Function? onerror;
  void close();
};

dictionary EventSourceInit {
  boolean withCredentials = false;
};

 　　EventSource()构造函数有一到两个参数。第一个参数是指定的要连接的URL。第二个参数指定了设置，第二个参数是可选的，如果有的话，就以EventSourceInit字典的形式。当EventSource()构造函数被调用时，用户代理（UA）必须按下面的步骤执行：

　　1）解决第一个参数的URL，相当于输入脚本的base URL。

　　2）如果上步失败了，则投一个SyntaxError异常。

　　3）创建一个新的EventSource对象。

　　4）让CORS模式是匿名的。

　　5）如果第二个参数存在，并且withCredentials字典成员值是true，那么设置CORS模式为Use Credentials，初始化新的EventSource对象的withCredentials属性为true。

　　6）返回新的EventSource对象，继续在后台执行这些步骤（没有阻塞脚本）。

　　7）

　　当脚本的全局对象或者是一个Window对象或者是一个实现WorkerUtils接口的对象时，上面的构造方式必须是可见的。

　　传给构造函数的url属性必须是绝对URL。

　　withCredentials属性必须返回它上次初始化的值。当对象被创建，这个属性必须被初始化为false。

　　readyState属性代表了连接状态，它可以是下面的值：

　　CONNECTING（数字值是0）

　　　　连接没有被创建，或者连接被关，用户代理正在重新连接。

　　OPEN（数字值是1）

　　　　用户代理有一个连接，正在发布事件。

　　CLOSED（数字值是2）

　　　　连接没开，用户代理不试着重连接。或者是有一个重大的错误，或者是close()方法被调用。

　　当对象被创建，它的readyState属性必须被设置成CONNECTING（0）。

　　close()方法必须终止对于EventSource对象的fetch算法的任何实例，必须设置readyState属性为CLOSED。

　　下面是event handlers（它们相关于event handler event types），这些作为IDL属性，必须被支持，需要所有对象都实现EventSource接口：

　　另外，每个EventSource对象还有下面的东东：

　　1、重连接时间（reconnection time），在毫秒级，这个必须最初是用户代理设定的值。

　　2、上一个事件的ID字符串，这个必须初始化为空字符串。

　　这些值当前是不暴露给接口的。

4、处理模型

 

　　当数据被收到，被网络任务源排列的任务必须按照下面的内容处理数据。

 

5、判定一个事件流

6、解析事件流

7、注释

8、无连接push和其他features

9、垃圾回收