HTML — サーバから送信されるイベント

【この訳に特有な表記規約】

9.2.1. 序論

~serverが~web~pageに向けて — ~HTTP越しに, あるいは専用の “server-push” ~protocolを利用して — ~dataを~pushすることを可能化するため、 この仕様は， `EventSource$I ~interfaceを導入する。 ◎ To enable servers to push data to web pages over HTTP or using dedicated server-push protocols, this specification introduces the EventSource interface.

この~APIの利用-法は、 `EventSource$I ~objを作成して，~event~listenerを登録するだけである。 ◎ Using this API consists of creating an EventSource object and registering an event listener.

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

~server側の~script（この事例では `updates.cgi^l ）は、 ~MIME型に `text/event-stream$mt を伴う~messageを，次の形で送信する： ◎ On the server-side, the script ("updates.cgi" in this case) sends messages in the following form, with the text/event-stream MIME type:

data: 第一~message

data: 第二~message
data: この~messageは 2 行lからなる

data: 第三~message

【 各~messageは、 空行（言い換えれば，連続する 2 個以上の改行（ `end-of-line$P ））で終端する。 】【 この~pageの各~stream例は、 特に断らない限り，暗黙的に空行で終端されている。 】

作者は、 異なる~event型を利用することにより，各~eventを~~分類できる。 ここに 2 種の~event型 "`add^et", "`remove^et" が含まれた~streamがあるとする： ◎ Authors can separate events by using different event types. Here is a stream that has two event types, "add" and "remove":

event: add
data: 73857293

event: remove
data: 2153

event: add
data: 113411

そのような~streamを取扱う~scriptは、 次の様になろう （ %addHandler, %removeHandler は、 1 個の~event引数をとる関数とする）： ◎ The script to handle such a stream would look like this (where addHandler and removeHandler are functions that take one argument, the event):

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

既定の~event型は "`message^et" である。 【すなわち、最初の例のように "`event:^c" 行lが省略された場合。】 ◎ The default event type is "message".

~event~streamは、 常に~UTF-8として復号される。 別の文字~符号化法を指定する仕方はない。 ◎ Event streams are always decoded as UTF-8. There is no way to specify another character encoding.

~event~stream要請は、 通常の~HTTP要請と同様に， ~HTTP［ `301$hst ／ `307$hst ］応答~codeにより~redirectされ得る（できる）。 接続が~closeされた場合、 ~clientは再接続することになる。 ~serverは、 ~HTTP `204$hst "No Content" 応答~codeを利用して， この再接続を停止するよう~clientに伝えれる。 ◎ Event stream requests can be redirected using HTTP 301 and 307 redirects as with normal HTTP requests. Clients will reconnect if the connection is closed; a client can be told to stop reconnecting using the HTTP 204 No Content response code.

この~APIを — `XMLHttpRequest$I や `iframe$e を利用してそれを模倣せずに — 利用すれば、 ~UAは — ~UAの実装者と~network運用者が高度に協調-可能な事例において — ~network資源をより良く利用できるようになる。 これには、 携帯機の~battery~~寿命を有意に節約できる便益もある — それについては、 `§ 無接続~push＠#eventsource-push$ にて更に論じられる。 ◎ Using this API rather than emulating it using XMLHttpRequest or an iframe allows the user agent to make better use of network resources in cases where the user agent implementer and the network operator are able to coordinate in advance. Amongst other benefits, this can result in significant savings in battery life on portable devices. This is discussed further in the section below on connectionless push.

9.2.2. `EventSource^I ~interface

[Exposed=(Window,Worker)]
interface `EventSource@I : `EventTarget$I {
  `EventSource$mc(USVString %url, optional `EventSourceInit$I %eventSourceInitDict = {});

  readonly attribute USVString `url$m;
  readonly attribute boolean `withCredentials$m;

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

  // networking
  attribute `EventHandler$I `onopen$m;
  attribute `EventHandler$I `onmessage$m;
  attribute `EventHandler$I `onerror$m;
  undefined `close$m();
};

dictionary `EventSourceInit@I {
  boolean `~withCredentials0@m = false;
};

各 `EventSource$I ~objには、 次に挙げるものが結付けられる： ◎ Each EventSource object has the following associated with it:

`~URL@eS

`~URL~record$。 構築-時に設定される。 ◎ A url (a URL record). Set during construction.

`要請@eS

初期~時は ~NULL になるモノトスル。 ◎ A request. This must initially be null.

【 これもまた、 構築-時に ある`要請$に設定される。 】

`再接続~時間@eS

~milli秒数。 初期~時は`実装定義$な値 — おそらく，数秒を超えない~~範囲 — になるモノトスル。 ◎ A reconnection time, in milliseconds. This must initially be an implementation-defined value, probably in the region of a few seconds.

`最後の~event~ID文字列@eS

初期~時は空~文字列になるモノトスル。 ◎ A last event ID string. This must initially be the empty string.

`~URL$eSを除き、 現時点では，これらは `EventSource$I ~objに公開されていない。 ◎ Apart from url these are not currently exposed on the EventSource object.

%source = `new EventSource$m( %url [, { `~withCredentials0$m: true } ])

新たな `EventSource$I ~objを作成する。 ◎ Creates a new EventSource object.

%url は、 ~event~streamを供することになる資源の~URLを与える文字列。 ◎ url is a string giving the URL that will provide the event stream.

`~withCredentials0$m を ~T に設定すれば、 %url への接続~要請~用の`資格証~mode$rq は `include^l に設定されることになる。 ◎ Setting withCredentials to true will set the credentials mode for connection requests to url to "include".

%source.`close()$m

［ この `EventSource$I ~obj用に開始された`~fetch$~algoの~instance ］があれば，それらを中止した上で、 `readyState$m 属性を `CLOSED$m に設定する。 ◎ Aborts any instances of the fetch algorithm started for this EventSource object, and sets the readyState attribute to CLOSED.

%source.`url$m

`~event~streamを供している~URL$を返す。 ◎ Returns the URL providing the event stream.

%source.`withCredentials$m

`~event~streamを供している~URL$への接続~要請~用の`資格証~mode$rqに応じて［ `include^l ならば ~T ／ ~ELSE_ ~F ］を返す。 ◎ Returns true if the credentials mode for connection requests to the URL providing the event stream is set to "include", and false otherwise.

%source.`readyState$m

この `EventSource$I ~objの接続の状態を返す。 とり得る値は、 下に述べる。 ◎ Returns the state of this EventSource object's connection. It can have the values described below.

`readyState@m 属性は、 当の接続の状態を表現する： ◎ The readyState attribute represents the state of the connection.＼

• 取得子~手続きは【この項は、この訳による補完】 ⇒ ~RET 最後に設定された値

• 次のいずれかの値をとり得る： ◎ It can have the following values:

  `CONNECTING@m （数値 0 ）

  接続は、 まだ確立されていないか，または ~closeされていて~UAは再接続している。 ◎ The connection has not yet been established, or it was closed and the user agent is reconnecting.

  `OPEN@m （数値 1 ）

  ~UAは，~open接続を有していて、 ~eventが受信されるに伴い それを配送している。 ◎ The user agent has an open connection and is dispatching events as it receives them.

  `CLOSED@m （数値 2 ）

  接続は~openしておらず，~UAは再接続するよう試行していない。 何らかの致命的~errorがあったか， `close()$m ~methodが呼出された。 ◎ The connection is not open, and the user agent is not trying to reconnect. Either there was a fatal error or the close() method was invoked.

• コレの作成-時には、 `CONNECTING$m （ 0 ）に設定するモノトスル。 値がいつ変化するかは、 下に与える，接続を取扱うための規則にて定義される。 ◎ When the object is created its readyState must be set to CONNECTING (0). The rules given below for handling the connection define when the value changes.

`EventSource$I ~interfaceを実装している~すべての~objは、［ 以下に挙げる各種`~event~handler$, および対応する各種`~event~handler~event型$ ］を`~event~handler~IDL属性$として~supportするモノトスル： ◎ The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by all objects implementing the EventSource interface:

9.2.3. 処理~model

`~remote~event~task~source@ は、 `~task~source$であり， 各 `EventSource$I ~objにより`~queueされ$る すべての`~task$に利用される。 ◎ The task source for any tasks that are queued by EventSource objects is the remote event task source.

9.2.4. `Last-Event-ID^h ~header

`Last-Event-ID@h ~HTTP要請~headerは、 ~UAが`接続を確立し直す$ときに， `EventSource$I ~objの`最後の~event~ID文字列$eSを~serverへ報告する。 ◎ The Last-Event-ID` HTTP request header reports an EventSource object's last event ID string to the server when the user agent is to reestablish the connection.

値~空間を もっと良く定義することについては、 `課題 #7363＠~HTMLissue/7363$ を見よ。 それは、 本質的には，~UTF-8に符号化された文字列であって［ `0000^U `NULL^cn, `000A^U `LF^cn, `000D^U `CR^cn ］を包含しないものである。 ◎ See whatwg/html issue #7363 to define the value space better. It is essentially any UTF-8 encoded string, that does not contain U+0000 NULL, U+000A LF, or U+000D CR.

9.2.5. ~event~streamの構文解析

この~event~stream形式の`~MIME型$は、 `text/event-stream$mt である。 ◎ This event stream format's MIME type is text/event-stream.

~event~stream形式は、 次の `ABNF$r における `stream$P 生成規則で与えられる — この~ABNFの文字~集合は~Unicodeとする： ◎ The event stream format is as described by the stream production of the following ABNF, the character set for which is Unicode. [ABNF]

`stream@P
	= [ `bom$P ] *`event$P
`event@P
	= *( `comment$P / `field$P ) `end-of-line$P
`comment@P
	= `colon$P *`any-char$P `end-of-line$P
`field@P
	= 1*`name-char$P [ `colon$P [ `space$P ] *`any-char$P ] `end-of-line$P
`end-of-line@P
	= ( `cr$P `lf$P / `cr$P / `lf$P )

; 各種~文字
`lf@P
	= `000A^0x ; U+000A LINE FEED (LF)
`cr@P
	= `000D^0x ; U+000D CARRIAGE RETURN (CR)
`space@P
	= `0020^0x ; U+0020 SPACE
`colon@P
	= `003A^0x ; U+003A COLON (:)
`bom@P
	= `FEFF^0x ; U+FEFF BYTE ORDER MARK
`name-char@P
	= `0000-0009^0x / `000B-000C^0x / `000E-0039^0x / `003B-10FFFF^0x
	; 
`lf$P, `cr$P, `colon$P 以外の`~scalar値$
◎
; a scalar value other than U+000A LINE FEED (LF), U+000D CARRIAGE RETURN (CR), or U+003A COLON (:)

`any-char@P
	= `0000-0009^0x / `000B-000C^0x / `000E-10FFFF^0x
	; 
`lf$P, `cr$P 以外の`~scalar値$
◎
; a scalar value other than U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR)

この形式による~event~streamは、 常に ~UTF-8に符号化されなければナラナイ。 `ENCODING$r ◎ Event streams in this format must always be encoded as UTF-8. [ENCODING]

各 行lどうしは、 `end-of-line$P （［ `cr$P +`lf$P, `lf$P, `cr$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.

そのような資源~用に確立された~remote~serverへの接続は，長く生き残ることが予期されるので、 ~UAは，適切な~buffer法が利用されることを確保するべきである。 特に、［ 各 行lが 1 個の `lf$P で終端するように定義される~buffer法 ］は，安全である一方で、［ ~block~buffer法や, 異なる行l終端-法を期待する行l~buffer法 ］は，~event配送-を遅延させ得る。 ◎ 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 (LF) character is safe, block buffering or line buffering with different expected line endings can cause delays in event dispatch.

9.2.6. ~event~streamの解釈-法

~streamは、 `~UTF-8復号する$~algoで復号するモノトスル。 ◎ Streams must be decoded using the UTF-8 decode algorithm.

注記： `~UTF-8復号する$~algoは、 先頭に~UTF-8 Byte Order Mark （ `bom$P ）があれば それを剥ぎ取る。 ◎ The UTF-8 decode algorithm strips one leading UTF-8 Byte Order Mark (BOM), if any.

~streamを構文解析する~algoの各~instanceには，［ %~data~buffer, %~event型~buffer, %最後の~event~ID~buffer ］が結付けられる — いずれも，空~文字列に初期化するモノトスル。 ◎ When a stream is parsed, a data buffer, an event type buffer, and a last event ID buffer must be associated with it. They must be initialized to the empty string.

~streamの終端に達した時点で，最後の~blockが空行で終端されていない場合、 その~blockの~dataを破棄するモノトスル。 （そのような~blockに対しては、 ~eventは配送されない。） （~blockとは、 空行で分離されていない，一連の行lを意味する。） ◎ Once the end of the file is reached, any pending data must be discarded. (If the file ends in the middle of an event, before the final empty line, the incomplete event is not dispatched.)

event: add
event: remove
data: 1234

~UAは、 `~message~eventを配送する@ 【！~eventを配送する】 よう要求されたときは、 ( %~data~buffer, %~event型~buffer, %最後の~event~ID~buffer ) を~UAに適切な手続きを利用して処理するモノトスル。 ◎ When the user agent is required to dispatch the event, the user agent must process the data buffer, the event type buffer, and the last event ID buffer using steps appropriate for the user agent.

注記： ~event（ `event$P ）に `id^l ~fieldが伴われていない場合、［ その~eventから生じる `MessageEvent$I ~event の `lastEventId$m ］は，最後に~~見出された `id^l ~fieldの値 — すなわち，以前の~eventにより設定された`最後の~event~ID文字列$eS 【 `id^l がまだ~~見出されていない場合は，空~文字列（ %最後の~event~ID~buffer の初期~値）】 — に設定されることになる。 ◎ If an event doesn't have an "id" field, but an earlier event did set the event source's last event ID string, then the event's lastEventId field will be set to the value of whatever the last seen "id" field was.

他の~UA用には、 `~message~eventを配送する$ための適切な手続きは，実装に依存するが、 最小限，手続きを終える前に［ %~data~buffer, %~event型~buffer ］を空~文字列に設定するモノトスル。 ◎ For other user agents, the appropriate steps to dispatch the event are implementation dependent, but at a minimum they must set the data and event type buffers to the empty string before returning.

data: YHOO
data: +2
data: 10

var %stocks = new EventSource("https://stocks.example.com/ticker.php");
stocks.onmessage = function (%event) {
  var %data = %event.data.split('\n');
  updateStocks(%data[0], %data[1], %data[2]);
};

: test stream

data: first event
id: 1

data:second event
id

data:  third event

data

data
data

data:

data:test

data: test

9.2.7. 著作~上の注記

旧来の~proxy~serverは、 ある種の事例では，短い制限時間~後に~HTTP接続を落とすことが知られている。 作者は、 およそ毎 15 秒ごとに，~comment行l（`colon$P から開始される行l）を含ませることにより， そのような~proxy~serverに抗して保護できる。 ◎ 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.

~event~source接続を［ 互いに, あるいは以前に~serveされた特定の文書 ］に関係させたいと望む作者は、 ~IP~addressに依拠するのでは，うまく働かないことを見出すであろう — 同じ~clientが（複数の~proxy~serverを通すことに因り）複数の~IP~addressから接続することもあれば、 複数の~clientが（~proxy~serverを共有していることに因り）同じ~IP~addressから接続することもあるので。 文書を~serveするときに， その文書~内に一意な識別子を含ませておいて、 接続の確立-時に その識別子を~URLの一部として渡す方が良い。 ◎ 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 when the connection is established.

作者は，また、 ~HTTP~chunk法 【~HTTP11の `§ ~chunk化~転送~符号法＠~HTTPv1#chunked.encoding$】 は，この~protocolの信頼性に期待されない負な効果を及ぼし得ることにも警戒すること — 特に、 ~chunk法が計時~要件を自覚しない層で行われている場合には。 これが問題になる場合、 ~event~streamを~serveするときに，~chunk法を不能化できる。 ◎ Authors are also cautioned that HTTP chunking can have unexpected negative effects on the reliability of this protocol, in particular if the chunking is done by a different layer unaware of the timing requirements. If this is a problem, chunking can be disabled for serving event streams.

9.2.8. 無接続~pushと他の特能

制御~下にある環境で走っている~UA — 例：特定の~carrierに束ねられている携帯機の~browser — は、 接続の管理を~network上の~proxyに負荷委譲してもヨイ。 適合性の目的においては、 そのような状況における~UAは， その携帯機~softwareと~network~proxyの両者を含むものと見なされる。 ◎ User agents running in controlled environments, e.g. browsers on mobile handsets tied to specific carriers, may offload the management of the connection to a proxy on the network. In such a situation, the user agent for the purposes of conformance is considered to include both the handset software and the network proxy.

これは、 総~data利用量を抑制するので，電力をかなり節約する。 ◎ This can reduce the total data usage, and can therefore result in considerable power savings.

［ 既存の~API, および `text/event-stream$mt 伝送路~形式 ］を［ この仕様により定義されるとおりに, および 上に述べたとおり より分散的な仕方で ］実装することに加え、 `適用-可能な仕様$により定義される［ ~event~frame法の形式 ］も~supportしてヨイ。 この仕様は、 それがどう構文解析され, 処理されるかは，定義しない。 ◎ As well as implementing the existing API and text/event-stream wire format as defined by this specification and in more distributed ways as described above, formats of event framing defined by other applicable specifications may be supported. This specification does not define how they are to be parsed or processed.

9.2.9. ~garbage収集

［ `Window$I ／ `WorkerGlobalScope$I ］~obj %G の構築子を呼出して作成された `EventSource$I ~obj %O に対しては、 ~OR↓ が満たされている間は， %G から %O への強い参照-があるモノトスル： ◎ ↓

• ［ %O の `readyState$m ~EQ `CONNECTING$m ］~AND［ %O には［ `open$et ／ `message$et ／`error$et ］~event用の~event~listenerが 1 個~以上~登録されている ］ ◎ While an EventSource object's readyState is CONNECTING, and the object has one or more event listeners registered for open, message or error events, there must be a strong reference from the Window or WorkerGlobalScope object that the EventSource object's constructor was invoked from to the EventSource object itself.
• ［ %O の `readyState$m ~EQ `OPEN$m ］~AND［ %O には［ `message$et ／ `error$et ］~event用の~event~listenerが 1 個~以上~登録されている ］ ◎ While an EventSource object's readyState is OPEN, and the object has one or more event listeners registered for message or error events, there must be a strong reference from the Window or WorkerGlobalScope object that the EventSource object's constructor was invoked from to the EventSource object itself.
• %O により`~remote~event~task~source$から~queueされた~taskが在る ◎ While there is a task queued by an EventSource object on the remote event task source, there must be a strong reference from the Window or WorkerGlobalScope object that the EventSource object's constructor was invoked from to that EventSource object.

`EventSource$I ~obj %O が，接続が依然として~openしている間に~garbage収集された場合、 ~UAは， %O 用に開始された すべての`~fetch$~algoを中止するモノトスル。 ◎ If an EventSource object is garbage collected while its connection is still open, the user agent must abort any instance of the fetch algorithm opened by this EventSource.

9.2.10. 実装~向けの助言

この~APIを利用している作者による~codeの~debugを援助するため、 ~UAには，［［ `EventSource$I ~obj, および それに関係する~network接続 ］についての詳細な診断~情報 ］を開発~console内に供することが強く督促される。 ◎ User agents are strongly urged to provide detailed diagnostic information about EventSource objects and their related network connections in their development consoles, to aid authors in debugging code using this API.

例えば~UAは、 ~pageが作成した各 `EventSource$I ~obj用に， 次に挙げるもの等々を表示する~panelを備えることもできる： ◎ For example, a user agent could have a panel displaying all the EventSource objects a page has created, each listing＼

• 構築子の引数 ◎ the constructor's arguments,＼
• ~network~errorが生じたかどうか ◎ whether there was a network error,＼
• 接続の~CORS状態s — および，その状態sに至らせたのは （~clientが送信した／~serverから受信した）どの~headerたちか ◎ what the CORS status of the connection is and what headers were sent by the client and received from the server to lead to that status,＼
• 受信した~message — および，それは どう構文解析されたか ◎ the messages that were received and how they were parsed, and so forth.

とりわけ， `error$et ~eventが発火されたときには、 実装には［ 詳細な情報を自身の開発~consoleに報告する ］ことが奨励される — ~event自体から可用になる情報は少ししかないので。 ◎ Implementations are especially encouraged to report detailed information to their development consoles whenever an error event is fired, since little to no information can be made available in the events themselves.