Skip to content

Commit 682ed2a

Browse files
tulshitulshi
committed
merged latest main branch
2 parents 4208a6f + 03e926c commit 682ed2a

File tree

3 files changed

+123
-98
lines changed

3 files changed

+123
-98
lines changed

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

Lines changed: 52 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -3225,41 +3225,54 @@ <h5 id="name-reading-a-streams-status">
32253225
</li>
32263226
</ul>
32273227
<p id="section-7.1.2.1-7">On receiving a valid request the Event Transmitter responds with a 200 OK
3228-
response containing a <span><a href="#RFC7159" class="internal xref">JSON</a> [<a href="#RFC7159" class="cite xref">RFC7159</a>]</span> object with an attribute "status",
3229-
whose string value MUST have one of the following values:<a href="#section-7.1.2.1-7" class="pilcrow"></a></p>
3230-
<p id="section-7.1.2.1-8">enabled<a href="#section-7.1.2.1-8" class="pilcrow"></a></p>
3228+
response containing a <span><a href="#RFC7159" class="internal xref">JSON</a> [<a href="#RFC7159" class="cite xref">RFC7159</a>]</span> object with the following attributes:<a href="#section-7.1.2.1-7" class="pilcrow"></a></p>
3229+
<p id="section-7.1.2.1-8">status<a href="#section-7.1.2.1-8" class="pilcrow"></a></p>
32313230
<ul class="normal ulEmpty">
32323231
<li class="normal ulEmpty" id="section-7.1.2.1-9.1">
3233-
<p id="section-7.1.2.1-9.1.1">The Transmitter MUST transmit events over the stream, according to the
3234-
stream's configured delivery method.<a href="#section-7.1.2.1-9.1.1" class="pilcrow"></a></p>
3232+
<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>
32353233
</li>
32363234
</ul>
3237-
<p id="section-7.1.2.1-10">paused<a href="#section-7.1.2.1-10" class="pilcrow"></a></p>
3235+
<p id="section-7.1.2.1-10">reason<a href="#section-7.1.2.1-10" class="pilcrow"></a></p>
32383236
<ul class="normal ulEmpty">
32393237
<li class="normal ulEmpty" id="section-7.1.2.1-11.1">
3240-
<p id="section-7.1.2.1-11.1.1">The Transmitter MUST NOT transmit events over the stream. The transmitter
3238+
<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
3239+
the current value.<a href="#section-7.1.2.1-11.1.1" class="pilcrow"></a></p>
3240+
</li>
3241+
</ul>
3242+
<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>
3243+
<p id="section-7.1.2.1-13">enabled<a href="#section-7.1.2.1-13" class="pilcrow"></a></p>
3244+
<ul class="normal ulEmpty">
3245+
<li class="normal ulEmpty" id="section-7.1.2.1-14.1">
3246+
<p id="section-7.1.2.1-14.1.1">The Transmitter MUST transmit events over the stream, according to the
3247+
stream's configured delivery method.<a href="#section-7.1.2.1-14.1.1" class="pilcrow"></a></p>
3248+
</li>
3249+
</ul>
3250+
<p id="section-7.1.2.1-15">paused<a href="#section-7.1.2.1-15" class="pilcrow"></a></p>
3251+
<ul class="normal ulEmpty">
3252+
<li class="normal ulEmpty" id="section-7.1.2.1-16.1">
3253+
<p id="section-7.1.2.1-16.1.1">The Transmitter MUST NOT transmit events over the stream. The transmitter
32413254
will hold any events it would have transmitted while paused, and SHOULD
32423255
transmit them when the stream's status becomes "enabled". If a Transmitter
32433256
holds successive events that affect the same Subject Principal, then the
32443257
Transmitter MUST make sure that those events are transmitted in the order of
32453258
time that they were generated OR the Transmitter MUST send only the last events
32463259
that do not require the previous events affecting the same Subject Principal to
32473260
be processed by the Receiver, because the previous events are either cancelled
3248-
by the later events or the previous events are outdated.<a href="#section-7.1.2.1-11.1.1" class="pilcrow"></a></p>
3261+
by the later events or the previous events are outdated.<a href="#section-7.1.2.1-16.1.1" class="pilcrow"></a></p>
32493262
</li>
32503263
</ul>
3251-
<p id="section-7.1.2.1-12">disabled<a href="#section-7.1.2.1-12" class="pilcrow"></a></p>
3264+
<p id="section-7.1.2.1-17">disabled<a href="#section-7.1.2.1-17" class="pilcrow"></a></p>
32523265
<ul class="normal ulEmpty">
3253-
<li class="normal ulEmpty" id="section-7.1.2.1-13.1">
3254-
<p id="section-7.1.2.1-13.1.1">The Transmitter MUST NOT transmit events over the stream, and will not hold
3255-
any events for later transmission.<a href="#section-7.1.2.1-13.1.1" class="pilcrow"></a></p>
3266+
<li class="normal ulEmpty" id="section-7.1.2.1-18.1">
3267+
<p id="section-7.1.2.1-18.1.1">The Transmitter MUST NOT transmit events over the stream, and will not hold
3268+
any events for later transmission.<a href="#section-7.1.2.1-18.1.1" class="pilcrow"></a></p>
32563269
</li>
32573270
</ul>
3258-
<p id="section-7.1.2.1-14">The following is a non-normative example request to check an event stream's
3259-
status:<a href="#section-7.1.2.1-14" class="pilcrow"></a></p>
3271+
<p id="section-7.1.2.1-19">The following is a non-normative example request to check an event stream's
3272+
status:<a href="#section-7.1.2.1-19" class="pilcrow"></a></p>
32603273
<span id="name-example-check-stream-status"></span><div id="figstatusreq">
32613274
<figure id="figure-27">
3262-
<div class="lang-http sourcecode" id="section-7.1.2.1-15.1">
3275+
<div class="lang-http sourcecode" id="section-7.1.2.1-20.1">
32633276
<pre>
32643277
GET /ssf/status?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
32653278
Host: transmitter.example.com
@@ -3270,29 +3283,30 @@ <h5 id="name-reading-a-streams-status">
32703283
<a href="#name-example-check-stream-status" class="selfRef">Example: Check Stream Status Request</a>
32713284
</figcaption></figure>
32723285
</div>
3273-
<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>
3286+
<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>
32743287
<span id="name-example-check-stream-status-"></span><div id="figstatusresp">
32753288
<figure id="figure-28">
3276-
<div class="lang-http sourcecode" id="section-7.1.2.1-17.1">
3289+
<div class="lang-http sourcecode" id="section-7.1.2.1-22.1">
32773290
<pre>
32783291
HTTP/1.1 200 OK
32793292
Content-Type: application/json
32803293
Cache-Control: no-store
32813294

32823295
{
3283-
"status": "enabled"
3296+
"status": "paused",
3297+
"reason": "SYSTEM_DOWN_FOR_MAINTENANCE"
32843298
}
32853299
</pre>
32863300
</div>
32873301
<figcaption><a href="#figure-28" class="selfRef">Figure 28</a>:
32883302
<a href="#name-example-check-stream-status-" class="selfRef">Example: Check Stream Status Response</a>
32893303
</figcaption></figure>
32903304
</div>
3291-
<p id="section-7.1.2.1-18">The following is a non-normative example request to check an event stream's
3292-
status for a specific subject:<a href="#section-7.1.2.1-18" class="pilcrow"></a></p>
3305+
<p id="section-7.1.2.1-23">The following is a non-normative example request to check an event stream's
3306+
status for a specific subject:<a href="#section-7.1.2.1-23" class="pilcrow"></a></p>
32933307
<span id="name-example-check-stream-status-r"></span><div id="figstatuswithsubjectreq">
32943308
<figure id="figure-29">
3295-
<div class="lang-http sourcecode" id="section-7.1.2.1-19.1">
3309+
<div class="lang-http sourcecode" id="section-7.1.2.1-24.1">
32963310
<pre>
32973311
GET /ssf/status?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f&amp;subject=&lt;url-encoded-subject&gt; HTTP/1.1
32983312
Host: transmitter.example.com
@@ -3303,10 +3317,10 @@ <h5 id="name-reading-a-streams-status">
33033317
<a href="#name-example-check-stream-status-r" class="selfRef">Example: Check Stream Status Request with Subject</a>
33043318
</figcaption></figure>
33053319
</div>
3306-
<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>
3320+
<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>
33073321
<span id="name-example-check-stream-status-re"></span><div id="figstatuswithsubjectresp">
33083322
<figure id="figure-30">
3309-
<div class="alignLeft art-text artwork" id="section-7.1.2.1-21.1">
3323+
<div class="alignLeft art-text artwork" id="section-7.1.2.1-26.1">
33103324
<pre>
33113325
HTTP/1.1 200 OK
33123326
Content-Type: application/json
@@ -3329,7 +3343,7 @@ <h5 id="name-reading-a-streams-status">
33293343
<a href="#name-example-check-stream-status-re" class="selfRef">Example: Check Stream Status Response</a>
33303344
</figcaption></figure>
33313345
</div>
3332-
<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>
3346+
<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>
33333347
<span id="name-read-stream-status-errors"></span><div id="tabreadstatus">
33343348
<table class="center" id="table-6">
33353349
<caption>
@@ -3358,25 +3372,25 @@ <h5 id="name-reading-a-streams-status">
33583372
</tbody>
33593373
</table>
33603374
</div>
3361-
<p id="section-7.1.2.1-24">Examples:<a href="#section-7.1.2.1-24" class="pilcrow"></a></p>
3362-
<ol start="1" type="1" class="normal type-1" id="section-7.1.2.1-25">
3363-
<li id="section-7.1.2.1-25.1">If a Receiver makes a request with an invalid OAuth token, then the
3364-
Transmitter MUST respond with a 401 error status.<a href="#section-7.1.2.1-25.1" class="pilcrow"></a>
3375+
<p id="section-7.1.2.1-29">Examples:<a href="#section-7.1.2.1-29" class="pilcrow"></a></p>
3376+
<ol start="1" type="1" class="normal type-1" id="section-7.1.2.1-30">
3377+
<li id="section-7.1.2.1-30.1">If a Receiver makes a request with an invalid OAuth token, then the
3378+
Transmitter MUST respond with a 401 error status.<a href="#section-7.1.2.1-30.1" class="pilcrow"></a>
33653379
</li>
3366-
<li id="section-7.1.2.1-25.2">If the Receiver presents a valid OAuth token, but the Transmitter policy
3380+
<li id="section-7.1.2.1-30.2">If the Receiver presents a valid OAuth token, but the Transmitter policy
33673381
does not permit the Receiver from obtaining the status, then the Transmitter
3368-
MAY respond with a 403 error status.<a href="#section-7.1.2.1-25.2" class="pilcrow"></a>
3382+
MAY respond with a 403 error status.<a href="#section-7.1.2.1-30.2" class="pilcrow"></a>
33693383
</li>
3370-
<li id="section-7.1.2.1-25.3">If the Receiver requests the status for a stream that does not exist then the
3371-
Transmitter MUST respond with a 404 error status.<a href="#section-7.1.2.1-25.3" class="pilcrow"></a>
3384+
<li id="section-7.1.2.1-30.3">If the Receiver requests the status for a stream that does not exist then the
3385+
Transmitter MUST respond with a 404 error status.<a href="#section-7.1.2.1-30.3" class="pilcrow"></a>
33723386
</li>
3373-
<li id="section-7.1.2.1-25.4">If the Receiver requests the status for a specific Subject, but the
3387+
<li id="section-7.1.2.1-30.4">If the Receiver requests the status for a specific Subject, but the
33743388
Transmitter policy does not permit the Receiver to read the status of that
33753389
Subject, then the Transmitter MAY respond with a 404 error status in order
3376-
to not reveal the policy decision.<a href="#section-7.1.2.1-25.4" class="pilcrow"></a>
3390+
to not reveal the policy decision.<a href="#section-7.1.2.1-30.4" class="pilcrow"></a>
33773391
</li>
3378-
<li id="section-7.1.2.1-25.5">If the specified Subject is invalid then the Transmitter MUST respond with a
3379-
404 error status.<a href="#section-7.1.2.1-25.5" class="pilcrow"></a>
3392+
<li id="section-7.1.2.1-30.5">If the specified Subject is invalid then the Transmitter MUST respond with a
3393+
404 error status.<a href="#section-7.1.2.1-30.5" class="pilcrow"></a>
33803394
</li>
33813395
</ol>
33823396
</section>
@@ -4560,7 +4574,7 @@ <h3 id="name-normative-references">
45604574
<dd class="break"></dd>
45614575
<dt id="RFC2119">[RFC2119]</dt>
45624576
<dd>
4563-
<span class="refAuthor">Bradner, S.</span>, <span class="refTitle">"Key words for use in RFCs to Indicate Requirement Levels"</span>, <span class="seriesInfo">BCP 14</span>, <span class="seriesInfo">RFC 2119</span>, <span class="seriesInfo">DOI 10.17487/RFC2119</span>, <time datetime="1997-03" class="refDate">March 1997</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc2119">https://www.rfc-editor.org/info/rfc2119</a>&gt;</span>. </dd>
4577+
<span class="refAuthor">Bradner, S.</span>, <span class="refTitle">"Key words for use in RFCs to Indicate Requirement Levels"</span>, <span class="seriesInfo">BCP 14</span>, <span class="seriesInfo">RFC 2119</span>, <span class="seriesInfo">DOI 10.17487/RFC2119</span>, <time datetime="1997-03" class="refDate">March 1997</time>, <span>&lt;<a href="httpss://www.rfc-editor.org/info/rfc2119">httpss://www.rfc-editor.org/info/rfc2119</a>&gt;</span>. </dd>
45644578
<dd class="break"></dd>
45654579
<dt id="RFC5785">[RFC5785]</dt>
45664580
<dd>
@@ -4584,7 +4598,7 @@ <h3 id="name-normative-references">
45844598
<dd class="break"></dd>
45854599
<dt id="RFC8174">[RFC8174]</dt>
45864600
<dd>
4587-
<span class="refAuthor">Leiba, B.</span>, <span class="refTitle">"Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"</span>, <span class="seriesInfo">BCP 14</span>, <span class="seriesInfo">RFC 8174</span>, <span class="seriesInfo">DOI 10.17487/RFC8174</span>, <time datetime="2017-05" class="refDate">May 2017</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc8174">https://www.rfc-editor.org/info/rfc8174</a>&gt;</span>. </dd>
4601+
<span class="refAuthor">Leiba, B.</span>, <span class="refTitle">"Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"</span>, <span class="seriesInfo">BCP 14</span>, <span class="seriesInfo">RFC 8174</span>, <span class="seriesInfo">DOI 10.17487/RFC8174</span>, <time datetime="2017-05" class="refDate">May 2017</time>, <span>&lt;<a href="httpss://www.rfc-editor.org/info/rfc8174">httpss://www.rfc-editor.org/info/rfc8174</a>&gt;</span>. </dd>
45884602
<dd class="break"></dd>
45894603
<dt id="RFC8417">[RFC8417]</dt>
45904604
<dd>

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

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1441,8 +1441,18 @@ subject
14411441
> OPTIONAL. The subject for which the stream status is requested.
14421442

14431443
On receiving a valid request the Event Transmitter responds with a 200 OK
1444-
response containing a [JSON][RFC7159] object with an attribute "status",
1445-
whose string value MUST have one of the following values:
1444+
response containing a [JSON][RFC7159] object with the following attributes:
1445+
1446+
status
1447+
1448+
> A string whose value MUST be one of the values described below.
1449+
1450+
reason
1451+
1452+
> An OPTIONAL string whose value SHOULD express why the stream's status is set to
1453+
the current value.
1454+
1455+
The allowable "status" values are:
14461456

14471457
enabled
14481458

@@ -1484,7 +1494,8 @@ Content-Type: application/json
14841494
Cache-Control: no-store
14851495

14861496
{
1487-
"status": "enabled"
1497+
"status": "paused",
1498+
"reason": "SYSTEM_DOWN_FOR_MAINTENANCE"
14881499
}
14891500
~~~
14901501
{: title="Example: Check Stream Status Response" #figstatusresp}
@@ -1942,7 +1953,7 @@ sub_id
19421953
> REQUIRED. The top-level `sub_id` claim specifies the Subject Principal for whom the status has been updated.
19431954
If the event applies to the entire stream, the value of the `sub_id` field
19441955
MUST be of format `opaque`, and its `id` value MUST be the unique ID of the
1945-
stream.
1956+
stream.
19461957

19471958
> Note that the subject that identifies a stream itself is always implicitly
19481959
added to the stream and MAY NOT be removed from the stream.

0 commit comments

Comments
 (0)