Skip to content

Commit

Permalink
Add reason to GET /status response (#86)
Browse files Browse the repository at this point in the history 
* Add reason to GET /status response

* Make reason look like an enum in the example to indicate how we expect it to be used
  • Loading branch information
@FragLegs
FragLegs authored Jul 25, 2023
1 parent 96bdc9e commit 03e926c
Show file tree
Hide file tree
Showing 3 changed files with 119 additions and 94 deletions.
86 changes: 50 additions & 36 deletions openid-sharedsignals-framework-1_0.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3127,41 +3127,54 @@ <h5 id="name-reading-a-streams-status">
</li>
</ul>
<p id="section-7.1.2.1-7">On receiving a valid request the Event Transmitter responds with a 200 OK
response containing a <span><a href="#RFC7159" class="xref">JSON</a> [<a href="#RFC7159" class="xref">RFC7159</a>]</span> object with an attribute "status",
whose string value MUST have one of the following values:<a href="#section-7.1.2.1-7" class="pilcrow"></a></p>
<p id="section-7.1.2.1-8">enabled<a href="#section-7.1.2.1-8" class="pilcrow"></a></p>
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>
<p id="section-7.1.2.1-8">status<a href="#section-7.1.2.1-8" class="pilcrow"></a></p>
<ul class="normal ulEmpty">
<li class="normal ulEmpty" id="section-7.1.2.1-9.1">
<p id="section-7.1.2.1-9.1.1">The Transmitter MUST transmit events over the stream, according to the
stream's configured delivery method.<a href="#section-7.1.2.1-9.1.1" class="pilcrow"></a></p>
<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>
</li>
</ul>
<p id="section-7.1.2.1-10">paused<a href="#section-7.1.2.1-10" class="pilcrow"></a></p>
<p id="section-7.1.2.1-10">reason<a href="#section-7.1.2.1-10" class="pilcrow"></a></p>
<ul class="normal ulEmpty">
<li class="normal ulEmpty" id="section-7.1.2.1-11.1">
<p id="section-7.1.2.1-11.1.1">The Transmitter MUST NOT transmit events over the stream. The transmitter
<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
the current value.<a href="#section-7.1.2.1-11.1.1" class="pilcrow"></a></p>
</li>
</ul>
<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>
<p id="section-7.1.2.1-13">enabled<a href="#section-7.1.2.1-13" class="pilcrow"></a></p>
<ul class="normal ulEmpty">
<li class="normal ulEmpty" id="section-7.1.2.1-14.1">
<p id="section-7.1.2.1-14.1.1">The Transmitter MUST transmit events over the stream, according to the
stream's configured delivery method.<a href="#section-7.1.2.1-14.1.1" class="pilcrow"></a></p>
</li>
</ul>
<p id="section-7.1.2.1-15">paused<a href="#section-7.1.2.1-15" class="pilcrow"></a></p>
<ul class="normal ulEmpty">
<li class="normal ulEmpty" id="section-7.1.2.1-16.1">
<p id="section-7.1.2.1-16.1.1">The Transmitter MUST NOT transmit events over the stream. The transmitter
will hold any events it would have transmitted while paused, and SHOULD
transmit them when the stream's status becomes "enabled". If a Transmitter
holds successive events that affect the same Subject Principal, then the
Transmitter MUST make sure that those events are transmitted in the order of
time that they were generated OR the Transmitter MUST send only the last events
that do not require the previous events affecting the same Subject Principal to
be processed by the Receiver, because the previous events are either cancelled
by the later events or the previous events are outdated.<a href="#section-7.1.2.1-11.1.1" class="pilcrow"></a></p>
by the later events or the previous events are outdated.<a href="#section-7.1.2.1-16.1.1" class="pilcrow"></a></p>
</li>
</ul>
<p id="section-7.1.2.1-12">disabled<a href="#section-7.1.2.1-12" class="pilcrow"></a></p>
<p id="section-7.1.2.1-17">disabled<a href="#section-7.1.2.1-17" class="pilcrow"></a></p>
<ul class="normal ulEmpty">
<li class="normal ulEmpty" id="section-7.1.2.1-13.1">
<p id="section-7.1.2.1-13.1.1">The Transmitter MUST NOT transmit events over the stream, and will not hold
any events for later transmission.<a href="#section-7.1.2.1-13.1.1" class="pilcrow"></a></p>
<li class="normal ulEmpty" id="section-7.1.2.1-18.1">
<p id="section-7.1.2.1-18.1.1">The Transmitter MUST NOT transmit events over the stream, and will not hold
any events for later transmission.<a href="#section-7.1.2.1-18.1.1" class="pilcrow"></a></p>
</li>
</ul>
<p id="section-7.1.2.1-14">The following is a non-normative example request to check an event stream's
status:<a href="#section-7.1.2.1-14" class="pilcrow"></a></p>
<p id="section-7.1.2.1-19">The following is a non-normative example request to check an event stream's
status:<a href="#section-7.1.2.1-19" class="pilcrow"></a></p>
<span id="name-example-check-stream-status"></span><div id="figstatusreq">
<figure id="figure-27">
<div id="section-7.1.2.1-15.1">
<div id="section-7.1.2.1-20.1">
<pre class="lang-http sourcecode">
GET /ssf/status?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
Host: transmitter.example.com
Expand All @@ -3172,29 +3185,30 @@ <h5 id="name-reading-a-streams-status">
<a href="#name-example-check-stream-status" class="selfRef">Example: Check Stream Status Request</a>
</figcaption></figure>
</div>
<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>
<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>
<span id="name-example-check-stream-status-"></span><div id="figstatusresp">
<figure id="figure-28">
<div id="section-7.1.2.1-17.1">
<div id="section-7.1.2.1-22.1">
<pre class="lang-http sourcecode">
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
"status": "enabled"
"status": "paused",
"reason": "SYSTEM_DOWN_FOR_MAINTENANCE"
}
</pre>
</div>
<figcaption><a href="#figure-28" class="selfRef">Figure 28</a>:
<a href="#name-example-check-stream-status-" class="selfRef">Example: Check Stream Status Response</a>
</figcaption></figure>
</div>
<p id="section-7.1.2.1-18">The following is a non-normative example request to check an event stream's
status for a specific subject:<a href="#section-7.1.2.1-18" class="pilcrow"></a></p>
<p id="section-7.1.2.1-23">The following is a non-normative example request to check an event stream's
status for a specific subject:<a href="#section-7.1.2.1-23" class="pilcrow"></a></p>
<span id="name-example-check-stream-status-r"></span><div id="figstatuswithsubjectreq">
<figure id="figure-29">
<div id="section-7.1.2.1-19.1">
<div id="section-7.1.2.1-24.1">
<pre class="lang-http sourcecode">
GET /ssf/status?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f&amp;subject=&lt;url-encoded-subject&gt; HTTP/1.1
Host: transmitter.example.com
Expand All @@ -3205,10 +3219,10 @@ <h5 id="name-reading-a-streams-status">
<a href="#name-example-check-stream-status-r" class="selfRef">Example: Check Stream Status Request with Subject</a>
</figcaption></figure>
</div>
<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>
<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>
<span id="name-example-check-stream-status-re"></span><div id="figstatuswithsubjectresp">
<figure id="figure-30">
<div class="alignLeft art-text artwork" id="section-7.1.2.1-21.1">
<div class="alignLeft art-text artwork" id="section-7.1.2.1-26.1">
<pre>
HTTP/1.1 200 OK
Content-Type: application/json
Expand All @@ -3231,7 +3245,7 @@ <h5 id="name-reading-a-streams-status">
<a href="#name-example-check-stream-status-re" class="selfRef">Example: Check Stream Status Response</a>
</figcaption></figure>
</div>
<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>
<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>
<span id="name-read-stream-status-errors"></span><div id="tabreadstatus">
<table class="center" id="table-6">
<caption>
Expand Down Expand Up @@ -3260,25 +3274,25 @@ <h5 id="name-reading-a-streams-status">
</tbody>
</table>
</div>
<p id="section-7.1.2.1-24">Examples:<a href="#section-7.1.2.1-24" class="pilcrow"></a></p>
<ol start="1" type="1" class="normal type-1" id="section-7.1.2.1-25">
<li id="section-7.1.2.1-25.1">If a Receiver makes a request with an invalid OAuth token, then the
Transmitter MUST respond with a 401 error status.<a href="#section-7.1.2.1-25.1" class="pilcrow"></a>
<p id="section-7.1.2.1-29">Examples:<a href="#section-7.1.2.1-29" class="pilcrow"></a></p>
<ol start="1" type="1" class="normal type-1" id="section-7.1.2.1-30">
<li id="section-7.1.2.1-30.1">If a Receiver makes a request with an invalid OAuth token, then the
Transmitter MUST respond with a 401 error status.<a href="#section-7.1.2.1-30.1" class="pilcrow"></a>
</li>
<li id="section-7.1.2.1-25.2">If the Receiver presents a valid OAuth token, but the Transmitter policy
<li id="section-7.1.2.1-30.2">If the Receiver presents a valid OAuth token, but the Transmitter policy
does not permit the Receiver from obtaining the status, then the Transmitter
MAY respond with a 403 error status.<a href="#section-7.1.2.1-25.2" class="pilcrow"></a>
MAY respond with a 403 error status.<a href="#section-7.1.2.1-30.2" class="pilcrow"></a>
</li>
<li id="section-7.1.2.1-25.3">If the Receiver requests the status for a stream that does not exist then the
Transmitter MUST respond with a 404 error status.<a href="#section-7.1.2.1-25.3" class="pilcrow"></a>
<li id="section-7.1.2.1-30.3">If the Receiver requests the status for a stream that does not exist then the
Transmitter MUST respond with a 404 error status.<a href="#section-7.1.2.1-30.3" class="pilcrow"></a>
</li>
<li id="section-7.1.2.1-25.4">If the Receiver requests the status for a specific Subject, but the
<li id="section-7.1.2.1-30.4">If the Receiver requests the status for a specific Subject, but the
Transmitter policy does not permit the Receiver to read the status of that
Subject, then the Transmitter MAY respond with a 404 error status in order
to not reveal the policy decision.<a href="#section-7.1.2.1-25.4" class="pilcrow"></a>
to not reveal the policy decision.<a href="#section-7.1.2.1-30.4" class="pilcrow"></a>
</li>
<li id="section-7.1.2.1-25.5">If the specified Subject is invalid then the Transmitter MUST respond with a
404 error status.<a href="#section-7.1.2.1-25.5" class="pilcrow"></a>
<li id="section-7.1.2.1-30.5">If the specified Subject is invalid then the Transmitter MUST respond with a
404 error status.<a href="#section-7.1.2.1-30.5" class="pilcrow"></a>
</li>
</ol>
</section>
Expand Down
21 changes: 16 additions & 5 deletions openid-sharedsignals-framework-1_0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1380,8 +1380,18 @@ subject
> OPTIONAL. The subject for which the stream status is requested.

On receiving a valid request the Event Transmitter responds with a 200 OK
response containing a [JSON][RFC7159] object with an attribute "status",
whose string value MUST have one of the following values:
response containing a [JSON][RFC7159] object with the following attributes:

status

> A string whose value MUST be one of the values described below.

reason

> An OPTIONAL string whose value SHOULD express why the stream's status is set to
the current value.

The allowable "status" values are:

enabled

Expand Down Expand Up @@ -1423,7 +1433,8 @@ Content-Type: application/json
Cache-Control: no-store

{
"status": "enabled"
"status": "paused",
"reason": "SYSTEM_DOWN_FOR_MAINTENANCE"
}
~~~
{: title="Example: Check Stream Status Response" #figstatusresp}
Expand Down Expand Up @@ -1883,7 +1894,7 @@ subject
> REQUIRED. Specifies the Subject Principal for whom the status has been updated.
If the event applies to the entire stream, the value of the `subject` field
MUST be of format `opaque`, and its `id` value MUST be the unique ID of the
stream.
stream.

> Note that the subject that identifies a stream itself is always implicitly
added to the stream and MAY NOT be removed from the stream.
Expand Down Expand Up @@ -1929,7 +1940,7 @@ subject
"subject": {
"format": "opaque",
"id" : "f67e39a0a4d34d56b3aa1bc4cff0069f"
},
},
"status": "paused",
"reason": "Internal error"
}
Expand Down
106 changes: 53 additions & 53 deletions openid-sharedsignals-framework-1_0.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1754,8 +1754,19 @@ Tulshibagwale, et al. Standards Track [Page 31]
OPTIONAL. The subject for which the stream status is requested.

On receiving a valid request the Event Transmitter responds with a
200 OK response containing a JSON [RFC7159] object with an attribute
"status", whose string value MUST have one of the following values:
200 OK response containing a JSON [RFC7159] object with the following
attributes:

status

A string whose value MUST be one of the values described below.

reason

An OPTIONAL string whose value SHOULD express why the stream's
status is set to the current value.

The allowable "status" values are:

enabled

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



Tulshibagwale, et al. Standards Track [Page 32]

SharedSignals June 2023


disabled

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






Tulshibagwale, et al. Standards Track [Page 32]

SharedSignals June 2023


GET /ssf/status?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer zzzz
Expand All @@ -1807,7 +1815,8 @@ Tulshibagwale, et al. Standards Track [Page 32]
Cache-Control: no-store

{
"status": "enabled"
"status": "paused",
"reason": "SYSTEM_DOWN_FOR_MAINTENANCE"
}

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













Tulshibagwale, et al. Standards Track [Page 33]

SharedSignals June 2023


HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Expand All @@ -1842,14 +1868,6 @@ Tulshibagwale, et al. Standards Track [Page 32]

Figure 30: Example: Check Stream Status Response




Tulshibagwale, et al. Standards Track [Page 33]

SharedSignals June 2023


Errors are signaled with HTTP status codes as follows:

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




Tulshibagwale, et al. Standards Track [Page 34]

SharedSignals June 2023


4. If the Receiver requests the status for a specific Subject, but
the Transmitter policy does not permit the Receiver to read the
status of that Subject, then the Transmitter MAY respond with a
Expand All @@ -1898,14 +1924,6 @@ Tulshibagwale, et al. Standards Track [Page 33]

REQUIRED. The stream whose status is being updated.




Tulshibagwale, et al. Standards Track [Page 34]

SharedSignals June 2023


status

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

Figure 31: Example: Update Stream Status Request Without Optional
Fields

The following is a non-normative example of an Update Stream Status
request with optional fields:
















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


Figure 31: Example: Update Stream Status Request Without Optional
Fields

The following is a non-normative example of an Update Stream Status
request with optional fields:

POST /ssf/status HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
Expand Down Expand Up @@ -2007,12 +2013,6 @@ Tulshibagwale, et al. Standards Track [Page 35]









Tulshibagwale, et al. Standards Track [Page 36]

SharedSignals June 2023
Expand Down

0 comments on commit 03e926c

Please sign in to comment.