Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add reason to GET /status response #86

Merged
merged 2 commits into from
Jul 25, 2023
Merged

Add reason to GET /status response #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b1c4476
Add reason to GET /status response
FragLegs Jul 21, 2023
3287ae5
Make reason look like an enum in the example to indicate how we expec…
FragLegs Jul 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 50 additions & 36 deletions openid-sharedsignals-framework-1_0.html
View file
Open in desktop
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
Open in desktop
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
Copy link
Contributor

@appsdesh appsdesh Jul 21, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking out loud here. Should we support I8N style reason similar to CAEP and RISC events?

            "reason": {
                "en": "System is down"
            },

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's an interesting idea. I was imagining that this reason would usually come from the Receiver via the reason field in the POST /status endpoint, but might sometimes come from an internal process within the Transmitter. Would we need to push that i8n to the POST /status endpoint as well?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the reason is for the human consumption it would make sense to include it in the POST request from the receiver during stream update call as well.

If this API is widely adopted and we are concerned about the compatibility issue while updating the request input then we could use a different key like receiver_ingested_reason or something similar in the POST request

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I spent some more time thinking about this over the weekend. I think that we should assume that "reason" acts like an enum. That is, whether a Receiver or Transmitter changes the status of the stream, it will be because of a programmatic response to events with a small set of possible reasons. We should assume that Transmitters will make known the possible reasons and Receivers will be aware of their own possible reasons. These strings are not really for human consumption, so I don't think we need to internationalize them.

Does that make sense to you? I can update the example reason to something like SYSTEM_DOWN to make it more obvious how we intend for these to be used.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense to me! Thanks for spending cycles. LGTM


> 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
Open in desktop
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
Loading