Skip to content

Commit 03e926c

Browse files
FragLegsFragLegs
authored
Add reason to GET /status response (#86)
* Add reason to GET /status response * Make reason look like an enum in the example to indicate how we expect it to be used
1 parent 96bdc9e commit 03e926c

File tree

3 files changed

+119
-94
lines changed

3 files changed

+119
-94
lines changed

‎openid-sharedsignals-framework-1_0.html‎

Lines changed: 50 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -3127,41 +3127,54 @@ <h5 id="name-reading-a-streams-status">
31273127
</li>
31283128
</ul>
31293129
<p id="section-7.1.2.1-7">On receiving a valid request the Event Transmitter responds with a 200 OK
3130-
response containing a <span><a href="#RFC7159" class="xref">JSON</a> [<a href="#RFC7159" class="xref">RFC7159</a>]</span> object with an attribute "status",
3131-
whose string value MUST have one of the following values:<a href="#section-7.1.2.1-7" class="pilcrow"></a></p>
3132-
<p id="section-7.1.2.1-8">enabled<a href="#section-7.1.2.1-8" class="pilcrow"></a></p>
3130+
response containing a <span><a href="#RFC7159" class="xref">JSON</a> [<a href="#RFC7159" class="xref">RFC7159</a>]</span> object with the following attributes:<a href="#section-7.1.2.1-7" class="pilcrow"></a></p>
3131+
<p id="section-7.1.2.1-8">status<a href="#section-7.1.2.1-8" class="pilcrow"></a></p>
31333132
<ul class="normal ulEmpty">
31343133
<li class="normal ulEmpty" id="section-7.1.2.1-9.1">
3135-
<p id="section-7.1.2.1-9.1.1">The Transmitter MUST transmit events over the stream, according to the
3136-
stream's configured delivery method.<a href="#section-7.1.2.1-9.1.1" class="pilcrow"></a></p>
3134+
<p id="section-7.1.2.1-9.1.1">A string whose value MUST be one of the values described below.<a href="#section-7.1.2.1-9.1.1" class="pilcrow"></a></p>
31373135
</li>
31383136
</ul>
3139-
<p id="section-7.1.2.1-10">paused<a href="#section-7.1.2.1-10" class="pilcrow"></a></p>
3137+
<p id="section-7.1.2.1-10">reason<a href="#section-7.1.2.1-10" class="pilcrow"></a></p>
31403138
<ul class="normal ulEmpty">
31413139
<li class="normal ulEmpty" id="section-7.1.2.1-11.1">
3142-
<p id="section-7.1.2.1-11.1.1">The Transmitter MUST NOT transmit events over the stream. The transmitter
3140+
<p id="section-7.1.2.1-11.1.1">An OPTIONAL string whose value SHOULD express why the stream's status is set to
3141+
the current value.<a href="#section-7.1.2.1-11.1.1" class="pilcrow"></a></p>
3142+
</li>
3143+
</ul>
3144+
<p id="section-7.1.2.1-12">The allowable "status" values are:<a href="#section-7.1.2.1-12" class="pilcrow"></a></p>
3145+
<p id="section-7.1.2.1-13">enabled<a href="#section-7.1.2.1-13" class="pilcrow"></a></p>
3146+
<ul class="normal ulEmpty">
3147+
<li class="normal ulEmpty" id="section-7.1.2.1-14.1">
3148+
<p id="section-7.1.2.1-14.1.1">The Transmitter MUST transmit events over the stream, according to the
3149+
stream's configured delivery method.<a href="#section-7.1.2.1-14.1.1" class="pilcrow"></a></p>
3150+
</li>
3151+
</ul>
3152+
<p id="section-7.1.2.1-15">paused<a href="#section-7.1.2.1-15" class="pilcrow"></a></p>
3153+
<ul class="normal ulEmpty">
3154+
<li class="normal ulEmpty" id="section-7.1.2.1-16.1">
3155+
<p id="section-7.1.2.1-16.1.1">The Transmitter MUST NOT transmit events over the stream. The transmitter
31433156
will hold any events it would have transmitted while paused, and SHOULD
31443157
transmit them when the stream's status becomes "enabled". If a Transmitter
31453158
holds successive events that affect the same Subject Principal, then the
31463159
Transmitter MUST make sure that those events are transmitted in the order of
31473160
time that they were generated OR the Transmitter MUST send only the last events
31483161
that do not require the previous events affecting the same Subject Principal to
31493162
be processed by the Receiver, because the previous events are either cancelled
3150-
by the later events or the previous events are outdated.<a href="#section-7.1.2.1-11.1.1" class="pilcrow"></a></p>
3163+
by the later events or the previous events are outdated.<a href="#section-7.1.2.1-16.1.1" class="pilcrow"></a></p>
31513164
</li>
31523165
</ul>
3153-
<p id="section-7.1.2.1-12">disabled<a href="#section-7.1.2.1-12" class="pilcrow"></a></p>
3166+
<p id="section-7.1.2.1-17">disabled<a href="#section-7.1.2.1-17" class="pilcrow"></a></p>
31543167
<ul class="normal ulEmpty">
3155-
<li class="normal ulEmpty" id="section-7.1.2.1-13.1">
3156-
<p id="section-7.1.2.1-13.1.1">The Transmitter MUST NOT transmit events over the stream, and will not hold
3157-
any events for later transmission.<a href="#section-7.1.2.1-13.1.1" class="pilcrow"></a></p>
3168+
<li class="normal ulEmpty" id="section-7.1.2.1-18.1">
3169+
<p id="section-7.1.2.1-18.1.1">The Transmitter MUST NOT transmit events over the stream, and will not hold
3170+
any events for later transmission.<a href="#section-7.1.2.1-18.1.1" class="pilcrow"></a></p>
31583171
</li>
31593172
</ul>
3160-
<p id="section-7.1.2.1-14">The following is a non-normative example request to check an event stream's
3161-
status:<a href="#section-7.1.2.1-14" class="pilcrow"></a></p>
3173+
<p id="section-7.1.2.1-19">The following is a non-normative example request to check an event stream's
3174+
status:<a href="#section-7.1.2.1-19" class="pilcrow"></a></p>
31623175
<span id="name-example-check-stream-status"></span><div id="figstatusreq">
31633176
<figure id="figure-27">
3164-
<div id="section-7.1.2.1-15.1">
3177+
<div id="section-7.1.2.1-20.1">
31653178
<pre class="lang-http sourcecode">
31663179
GET /ssf/status?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
31673180
Host: transmitter.example.com
@@ -3172,29 +3185,30 @@ <h5 id="name-reading-a-streams-status">
31723185
<a href="#name-example-check-stream-status" class="selfRef">Example: Check Stream Status Request</a>
31733186
</figcaption></figure>
31743187
</div>
3175-
<p id="section-7.1.2.1-16">The following is a non-normative example response:<a href="#section-7.1.2.1-16" class="pilcrow"></a></p>
3188+
<p id="section-7.1.2.1-21">The following is a non-normative example response:<a href="#section-7.1.2.1-21" class="pilcrow"></a></p>
31763189
<span id="name-example-check-stream-status-"></span><div id="figstatusresp">
31773190
<figure id="figure-28">
3178-
<div id="section-7.1.2.1-17.1">
3191+
<div id="section-7.1.2.1-22.1">
31793192
<pre class="lang-http sourcecode">
31803193
HTTP/1.1 200 OK
31813194
Content-Type: application/json
31823195
Cache-Control: no-store
31833196

31843197
{
3185-
"status": "enabled"
3198+
"status": "paused",
3199+
"reason": "SYSTEM_DOWN_FOR_MAINTENANCE"
31863200
}
31873201
</pre>
31883202
</div>
31893203
<figcaption><a href="#figure-28" class="selfRef">Figure 28</a>:
31903204
<a href="#name-example-check-stream-status-" class="selfRef">Example: Check Stream Status Response</a>
31913205
</figcaption></figure>
31923206
</div>
3193-
<p id="section-7.1.2.1-18">The following is a non-normative example request to check an event stream's
3194-
status for a specific subject:<a href="#section-7.1.2.1-18" class="pilcrow"></a></p>
3207+
<p id="section-7.1.2.1-23">The following is a non-normative example request to check an event stream's
3208+
status for a specific subject:<a href="#section-7.1.2.1-23" class="pilcrow"></a></p>
31953209
<span id="name-example-check-stream-status-r"></span><div id="figstatuswithsubjectreq">
31963210
<figure id="figure-29">
3197-
<div id="section-7.1.2.1-19.1">
3211+
<div id="section-7.1.2.1-24.1">
31983212
<pre class="lang-http sourcecode">
31993213
GET /ssf/status?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f&amp;subject=&lt;url-encoded-subject&gt; HTTP/1.1
32003214
Host: transmitter.example.com
@@ -3205,10 +3219,10 @@ <h5 id="name-reading-a-streams-status">
32053219
<a href="#name-example-check-stream-status-r" class="selfRef">Example: Check Stream Status Request with Subject</a>
32063220
</figcaption></figure>
32073221
</div>
3208-
<p id="section-7.1.2.1-20">The following is a non-normative example response with a Subject claim:<a href="#section-7.1.2.1-20" class="pilcrow"></a></p>
3222+
<p id="section-7.1.2.1-25">The following is a non-normative example response with a Subject claim:<a href="#section-7.1.2.1-25" class="pilcrow"></a></p>
32093223
<span id="name-example-check-stream-status-re"></span><div id="figstatuswithsubjectresp">
32103224
<figure id="figure-30">
3211-
<div class="alignLeft art-text artwork" id="section-7.1.2.1-21.1">
3225+
<div class="alignLeft art-text artwork" id="section-7.1.2.1-26.1">
32123226
<pre>
32133227
HTTP/1.1 200 OK
32143228
Content-Type: application/json
@@ -3231,7 +3245,7 @@ <h5 id="name-reading-a-streams-status">
32313245
<a href="#name-example-check-stream-status-re" class="selfRef">Example: Check Stream Status Response</a>
32323246
</figcaption></figure>
32333247
</div>
3234-
<p id="section-7.1.2.1-22">Errors are signaled with HTTP status codes as follows:<a href="#section-7.1.2.1-22" class="pilcrow"></a></p>
3248+
<p id="section-7.1.2.1-27">Errors are signaled with HTTP status codes as follows:<a href="#section-7.1.2.1-27" class="pilcrow"></a></p>
32353249
<span id="name-read-stream-status-errors"></span><div id="tabreadstatus">
32363250
<table class="center" id="table-6">
32373251
<caption>
@@ -3260,25 +3274,25 @@ <h5 id="name-reading-a-streams-status">
32603274
</tbody>
32613275
</table>
32623276
</div>
3263-
<p id="section-7.1.2.1-24">Examples:<a href="#section-7.1.2.1-24" class="pilcrow"></a></p>
3264-
<ol start="1" type="1" class="normal type-1" id="section-7.1.2.1-25">
3265-
<li id="section-7.1.2.1-25.1">If a Receiver makes a request with an invalid OAuth token, then the
3266-
Transmitter MUST respond with a 401 error status.<a href="#section-7.1.2.1-25.1" class="pilcrow"></a>
3277+
<p id="section-7.1.2.1-29">Examples:<a href="#section-7.1.2.1-29" class="pilcrow"></a></p>
3278+
<ol start="1" type="1" class="normal type-1" id="section-7.1.2.1-30">
3279+
<li id="section-7.1.2.1-30.1">If a Receiver makes a request with an invalid OAuth token, then the
3280+
Transmitter MUST respond with a 401 error status.<a href="#section-7.1.2.1-30.1" class="pilcrow"></a>
32673281
</li>
3268-
<li id="section-7.1.2.1-25.2">If the Receiver presents a valid OAuth token, but the Transmitter policy
3282+
<li id="section-7.1.2.1-30.2">If the Receiver presents a valid OAuth token, but the Transmitter policy
32693283
does not permit the Receiver from obtaining the status, then the Transmitter
3270-
MAY respond with a 403 error status.<a href="#section-7.1.2.1-25.2" class="pilcrow"></a>
3284+
MAY respond with a 403 error status.<a href="#section-7.1.2.1-30.2" class="pilcrow"></a>
32713285
</li>
3272-
<li id="section-7.1.2.1-25.3">If the Receiver requests the status for a stream that does not exist then the
3273-
Transmitter MUST respond with a 404 error status.<a href="#section-7.1.2.1-25.3" class="pilcrow"></a>
3286+
<li id="section-7.1.2.1-30.3">If the Receiver requests the status for a stream that does not exist then the
3287+
Transmitter MUST respond with a 404 error status.<a href="#section-7.1.2.1-30.3" class="pilcrow"></a>
32743288
</li>
3275-
<li id="section-7.1.2.1-25.4">If the Receiver requests the status for a specific Subject, but the
3289+
<li id="section-7.1.2.1-30.4">If the Receiver requests the status for a specific Subject, but the
32763290
Transmitter policy does not permit the Receiver to read the status of that
32773291
Subject, then the Transmitter MAY respond with a 404 error status in order
3278-
to not reveal the policy decision.<a href="#section-7.1.2.1-25.4" class="pilcrow"></a>
3292+
to not reveal the policy decision.<a href="#section-7.1.2.1-30.4" class="pilcrow"></a>
32793293
</li>
3280-
<li id="section-7.1.2.1-25.5">If the specified Subject is invalid then the Transmitter MUST respond with a
3281-
404 error status.<a href="#section-7.1.2.1-25.5" class="pilcrow"></a>
3294+
<li id="section-7.1.2.1-30.5">If the specified Subject is invalid then the Transmitter MUST respond with a
3295+
404 error status.<a href="#section-7.1.2.1-30.5" class="pilcrow"></a>
32823296
</li>
32833297
</ol>
32843298
</section>

‎openid-sharedsignals-framework-1_0.md‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1380,8 +1380,18 @@ subject
13801380
> OPTIONAL. The subject for which the stream status is requested.
13811381

13821382
On receiving a valid request the Event Transmitter responds with a 200 OK
1383-
response containing a [JSON][RFC7159] object with an attribute "status",
1384-
whose string value MUST have one of the following values:
1383+
response containing a [JSON][RFC7159] object with the following attributes:
1384+
1385+
status
1386+
1387+
> A string whose value MUST be one of the values described below.
1388+
1389+
reason
1390+
1391+
> An OPTIONAL string whose value SHOULD express why the stream's status is set to
1392+
the current value.
1393+
1394+
The allowable "status" values are:
13851395

13861396
enabled
13871397

@@ -1423,7 +1433,8 @@ Content-Type: application/json
14231433
Cache-Control: no-store
14241434

14251435
{
1426-
"status": "enabled"
1436+
"status": "paused",
1437+
"reason": "SYSTEM_DOWN_FOR_MAINTENANCE"
14271438
}
14281439
~~~
14291440
{: title="Example: Check Stream Status Response" #figstatusresp}
@@ -1883,7 +1894,7 @@ subject
18831894
> REQUIRED. Specifies the Subject Principal for whom the status has been updated.
18841895
If the event applies to the entire stream, the value of the `subject` field
18851896
MUST be of format `opaque`, and its `id` value MUST be the unique ID of the
1886-
stream.
1897+
stream.
18871898

18881899
> Note that the subject that identifies a stream itself is always implicitly
18891900
added to the stream and MAY NOT be removed from the stream.
@@ -1929,7 +1940,7 @@ subject
19291940
"subject": {
19301941
"format": "opaque",
19311942
"id" : "f67e39a0a4d34d56b3aa1bc4cff0069f"
1932-
},
1943+
},
19331944
"status": "paused",
19341945
"reason": "Internal error"
19351946
}

‎openid-sharedsignals-framework-1_0.txt‎

Lines changed: 53 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1754,8 +1754,19 @@ Tulshibagwale, et al. Standards Track [Page 31]
17541754
OPTIONAL. The subject for which the stream status is requested.
17551755

17561756
On receiving a valid request the Event Transmitter responds with a
1757-
200 OK response containing a JSON [RFC7159] object with an attribute
1758-
"status", whose string value MUST have one of the following values:
1757+
200 OK response containing a JSON [RFC7159] object with the following
1758+
attributes:
1759+
1760+
status
1761+
1762+
A string whose value MUST be one of the values described below.
1763+
1764+
reason
1765+
1766+
An OPTIONAL string whose value SHOULD express why the stream's
1767+
status is set to the current value.
1768+
1769+
The allowable "status" values are:
17591770

17601771
enabled
17611772

@@ -1776,6 +1787,13 @@ Tulshibagwale, et al. Standards Track [Page 31]
17761787
events are either cancelled by the later events or the previous
17771788
events are outdated.
17781789

1790+
1791+
1792+
Tulshibagwale, et al. Standards Track [Page 32]
1793+
1794+
SharedSignals June 2023
1795+
1796+
17791797
disabled
17801798

17811799
The Transmitter MUST NOT transmit events over the stream, and will
@@ -1784,16 +1802,6 @@ Tulshibagwale, et al. Standards Track [Page 31]
17841802
The following is a non-normative example request to check an event
17851803
stream's status:
17861804

1787-
1788-
1789-
1790-
1791-
1792-
Tulshibagwale, et al. Standards Track [Page 32]
1793-
1794-
SharedSignals June 2023
1795-
1796-
17971805
GET /ssf/status?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
17981806
Host: transmitter.example.com
17991807
Authorization: Bearer zzzz
@@ -1807,7 +1815,8 @@ Tulshibagwale, et al. Standards Track [Page 32]
18071815
Cache-Control: no-store
18081816

18091817
{
1810-
"status": "enabled"
1818+
"status": "paused",
1819+
"reason": "SYSTEM_DOWN_FOR_MAINTENANCE"
18111820
}
18121821

18131822
Figure 28: Example: Check Stream Status Response
@@ -1824,6 +1833,23 @@ Tulshibagwale, et al. Standards Track [Page 32]
18241833
The following is a non-normative example response with a Subject
18251834
claim:
18261835

1836+
1837+
1838+
1839+
1840+
1841+
1842+
1843+
1844+
1845+
1846+
1847+
1848+
Tulshibagwale, et al. Standards Track [Page 33]
1849+
1850+
SharedSignals June 2023
1851+
1852+
18271853
HTTP/1.1 200 OK
18281854
Content-Type: application/json
18291855
Cache-Control: no-store
@@ -1842,14 +1868,6 @@ Tulshibagwale, et al. Standards Track [Page 32]
18421868

18431869
Figure 30: Example: Check Stream Status Response
18441870

1845-
1846-
1847-
1848-
Tulshibagwale, et al. Standards Track [Page 33]
1849-
1850-
SharedSignals June 2023
1851-
1852-
18531871
Errors are signaled with HTTP status codes as follows:
18541872

18551873
+======+========================================================+
@@ -1880,6 +1898,14 @@ Tulshibagwale, et al. Standards Track [Page 33]
18801898
3. If the Receiver requests the status for a stream that does not
18811899
exist then the Transmitter MUST respond with a 404 error status.
18821900

1901+
1902+
1903+
1904+
Tulshibagwale, et al. Standards Track [Page 34]
1905+
1906+
SharedSignals June 2023
1907+
1908+
18831909
4. If the Receiver requests the status for a specific Subject, but
18841910
the Transmitter policy does not permit the Receiver to read the
18851911
status of that Subject, then the Transmitter MAY respond with a
@@ -1898,14 +1924,6 @@ Tulshibagwale, et al. Standards Track [Page 33]
18981924

18991925
REQUIRED. The stream whose status is being updated.
19001926

1901-
1902-
1903-
1904-
Tulshibagwale, et al. Standards Track [Page 34]
1905-
1906-
SharedSignals June 2023
1907-
1908-
19091927
status
19101928

19111929
REQUIRED. The new status of the Event Stream.
@@ -1935,24 +1953,6 @@ Tulshibagwale, et al. Standards Track [Page 34]
19351953
"status": "paused"
19361954
}
19371955

1938-
Figure 31: Example: Update Stream Status Request Without Optional
1939-
Fields
1940-
1941-
The following is a non-normative example of an Update Stream Status
1942-
request with optional fields:
1943-
1944-
1945-
1946-
1947-
1948-
1949-
1950-
1951-
1952-
1953-
1954-
1955-
19561956

19571957

19581958

@@ -1962,6 +1962,12 @@ Tulshibagwale, et al. Standards Track [Page 35]
19621962
SharedSignals June 2023
19631963

19641964

1965+
Figure 31: Example: Update Stream Status Request Without Optional
1966+
Fields
1967+
1968+
The following is a non-normative example of an Update Stream Status
1969+
request with optional fields:
1970+
19651971
POST /ssf/status HTTP/1.1
19661972
Host: transmitter.example.com
19671973
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
@@ -2007,12 +2013,6 @@ Tulshibagwale, et al. Standards Track [Page 35]
20072013

20082014

20092015

2010-
2011-
2012-
2013-
2014-
2015-
20162016
Tulshibagwale, et al. Standards Track [Page 36]
20172017

20182018
SharedSignals June 2023

0 commit comments

Comments
 (0)