Add Stream ID #9

FragLegs · 2022-05-04T19:36:14Z

This PR does a number of things:

Most notably, it implements the changed described in issue Adding a Stream ID #4 - Adding a Stream ID
It reorders the sections so that information about creating/updating/deleting the stream comes before information about setting/getting the stream status
It adds Shayne Miel as a coauthor
It adds some info to the README to help others who might work on the spec

FragLegs · 2022-05-04T19:40:55Z

However, there is a slight wrinkle with the stream ID that I didn't foresee. How should we indicate to transmitters and receivers that they need a way to identify which stream is being POLLed or PUSHed?

For PUSH it is easy - we can leave it up to the Receiver to set either a URL param in the endpoint or use a specific endpoint that dictates the stream ID. It is a little complicated though since the Receiver does not know the stream ID when creating the stream, which would force them to provide the "delivery" info during a second request. How much of this should we call out in the spec?

For POLL it is up to the Transmitter to do the right thing and add a URL param or a specific endpoint for each stream. Do we need to call that out in the spec?

A third option would be to extend the POLL spec to include a stream_id parameter, but that seems like a big lift.

adeinega · 2022-08-09T20:16:37Z

As an (almost) completely random comment, it would be great to keep only *.md documents in the repo, for example, openid-sse-framework-1_0.md, and then

use https://github.com/cabo/kramdown-rfc to convert *.md to *.xml
convert *.xml using xml2rfc to txt and HTML files when you they need to be published in other (external) places

It'll allow keeping the number of changes very low and easily review them. Moreover, Markdown files are convenient to edit even though the Web UI of GitHub.

timcappalli · 2022-08-29T00:37:54Z

As an (almost) completely random comment, it would be great to keep only *.md documents in the repo, for example, openid-sse-framework-1_0.md, and then

use https://github.com/cabo/kramdown-rfc to convert *.md to *.xml

convert *.xml using xml2rfc to txt and HTML files when you they need to be published in other (external) places

It'll allow keeping the number of changes very low and easily review them. Moreover, Markdown files are convenient to edit even though the Web UI of GitHub.

that's the plan. Just haven't had a change to convert the others to MD and then set up GH actions

… URLs

FragLegs · 2022-09-13T13:34:12Z

However, there is a slight wrinkle with the stream ID that I didn't foresee. How should we indicate to transmitters and receivers that they need a way to identify which stream is being POLLed or PUSHed?

For PUSH it is easy - we can leave it up to the Receiver to set either a URL param in the endpoint or use a specific endpoint that dictates the stream ID. It is a little complicated though since the Receiver does not know the stream ID when creating the stream, which would force them to provide the "delivery" info during a second request. How much of this should we call out in the spec?

For POLL it is up to the Transmitter to do the right thing and add a URL param or a specific endpoint for each stream. Do we need to call that out in the spec?

A third option would be to extend the POLL spec to include a stream_id parameter, but that seems like a big lift.

I added notes in the PUSH/POLL section to indicate the uniqueness needs of the URLs.

tulshi · 2022-09-15T23:53:49Z

In the Transmitter Configuration Metadata, should we modify the "delivery methods supported" to include the POLL URL if the method is POLL?

…

On Tue, Sep 13, 2022 at 6:34 AM FragLegs ***@***.***> wrote: However, there is a slight wrinkle with the stream ID that I didn't foresee. How should we indicate to transmitters and receivers that they need a way to identify which stream is being POLLed or PUSHed? For PUSH it is easy - we can leave it up to the Receiver to set either a URL param in the endpoint or use a specific endpoint that dictates the stream ID. It is a little complicated though since the Receiver does not know the stream ID when creating the stream, which would force them to provide the "delivery" info during a second request. How much of this should we call out in the spec? For POLL it is up to the Transmitter to do the right thing and add a URL param or a specific endpoint for each stream. Do we need to call that out in the spec? A third option would be to extend the POLL spec to include a stream_id parameter, but that seems like a big lift. I added notes in the PUSH/POLL section to indicate the uniqueness needs of the URLs. — Reply to this email directly, view it on GitHub <#9 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB55UGYF2DEXPXDTHOW7SKDV6B7F7ANCNFSM5VC65TEA> . You are receiving this because your review was requested.Message ID: ***@***.***>

FragLegs · 2022-09-16T01:33:43Z

That’s a good idea, but can we make it a separate issue/PR? I think there’s enough to discuss there to warrant a separate issue. On Thu, Sep 15, 2022 at 7:54 PM Atul Tulshibagwale ***@***.***> wrote:

…

In the Transmitter Configuration Metadata, should we modify the "delivery methods supported" to include the POLL URL if the method is POLL? On Tue, Sep 13, 2022 at 6:34 AM FragLegs ***@***.***> wrote: > However, there is a slight wrinkle with the stream ID that I didn't > foresee. How should we indicate to transmitters and receivers that they > need a way to identify which stream is being POLLed or PUSHed? > > For PUSH it is easy - we can leave it up to the Receiver to set either a > URL param in the endpoint or use a specific endpoint that dictates the > stream ID. It is a little complicated though since the Receiver does not > know the stream ID when creating the stream, which would force them to > provide the "delivery" info during a second request. How much of this > should we call out in the spec? > > For POLL it is up to the Transmitter to do the right thing and add a URL > param or a specific endpoint for each stream. Do we need to call that out > in the spec? > > A third option would be to extend the POLL spec to include a stream_id > parameter, but that seems like a big lift. > > I added notes in the PUSH/POLL section to indicate the uniqueness needs of > the URLs. > > — > Reply to this email directly, view it on GitHub > <#9 (comment)>, or > unsubscribe > < https://github.com/notifications/unsubscribe-auth/AB55UGYF2DEXPXDTHOW7SKDV6B7F7ANCNFSM5VC65TEA > > . > You are receiving this because your review was requested.Message ID: > ***@***.***> > — Reply to this email directly, view it on GitHub <#9 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHK3GG52J755CCR5DAO2D3V6OZJPANCNFSM5VC65TEA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

tulshi · 2022-11-17T00:29:41Z

openid-sse-framework-1_0.txt

-   update the Event Stream configuration and status, to add and remove
-   subjects and to trigger verification.
+   Transmitters which can be used by Event Receivers to create and
+   delete one or more Event Streams, query and update the configuration


Since we are talking about multiple event streams now, we should probably write a new section that defines what an event stream is.

openid-sse-framework-1_0.txt

tulshi · 2022-11-17T01:23:44Z

openid-sse-framework-1_0.txt

-   would make the following request to the Issuer
-   "https://tr.example.com/issuer1" to obtain its Configuration
-   information, since the Issuer contains a path component:
+   If the Issuer value contains a path component, any terminating / MUST


I've noticed that the quotes are gone from many places in the spec. Is that intentional or an artifact of the tools you are using?

Will be fixed by #35

tulshi · 2022-11-17T01:24:19Z

openid-sse-framework-1_0.txt

-   path component, if any.  The syntax and semantics of ".well-known"
-   are defined in [RFC5785].  "sse-configuration" MUST point to a JSON
+   at the path formed by inserting the string /.well-known/sse-
+   configuration into the Issuer between the host component and the path


I think the quotes are important here, otherwise the spec cannot be read unambiguously

Will be fixed by #35

openid-sse-framework-1_0.txt

tulshi · 2022-11-18T00:36:33Z

openid-sse-framework-1_0.txt

+
+                     Table 6: Read Stream Status Errors
+
+   Examples:


These examples apply to all API calls. Should we move them to a part of the API description that applies to all calls?

Yes. I think the examples sections all need a bit of rework. Some endpoints don't have examples, others (like this one) have examples that are too general. Since this was already in the spec, I'd like to leave it for a different pull request that is focused strictly on examples, if that's alright.

tulshi · 2022-11-18T00:38:38Z

openid-sse-framework-1_0.txt

+
+7.1.2.2.  Updating a Stream's Status
+
+   An Event Receiver updates the current status of a stream by making an


we should mark this for a later pull request, but this needs to be changed to a PATCH since it's an update.

👍 I'll make an issue for this and the examples comment above.

openid-sse-framework-1_0.txt

tulshi · 2022-11-18T00:56:37Z

openid-sse-framework-1_0.txt

-                          openid-sse-framework                 June 2021
-
+   subject
+      OPTIONAL.  Specifies the Subject Principal for whom the status has


If this is optional, then we should specify that omitting the subject from the event means that the event applies to all subjects in the stream.

topherMarie

I flagged a few typographical issues. As I am just now familiarizing myself with the spec, I'm not sure my approval should count for much.

topherMarie · 2022-11-29T18:57:07Z

openid-sse-framework-1_0.txt

+   stream_id
+      *Read-Only*, A string that uniquely identifies the stream.  Stream
+      IDs MAY be reused across Receivers, but MUST be unique per
+      Reciever.  This value is generated by the Transmitter when the


s/Reciever/Receiver

topherMarie · 2022-11-29T18:58:42Z

openid-sse-framework-1_0.txt

+   Subject Principals are the managed entities in a SSE Transmitter or
+   Receiver.  These include human or robotic principals, devices,
+   customer tenants in a multi-tenanted service, organizational units
+   within a tenant, groups of subject principals or other entities that


I personally like the Oxford comma for lists like this.

groups of service principals, or other entities...

topherMarie · 2022-11-30T15:37:33Z

openid-sse-framework-1_0.txt

-   error code.  See Security Considerations (Section 9).
+   empty 200 OK response.  The Event Transmitter MAY choose to silently
+   ignore the request, for example if the subject has previously
+   indicated to the transmitter that they do not want events to be


Transmitter is typically capitalized in this doc.

timcappalli

Some minor stuff relating to errors and status codes

openid-sse-framework-1_0.xml

tulshi

minor comments, but LGTM otherwise.

openid-sse-framework-1_0.xml

timcappalli

LGTM!

FragLegs requested review from timcappalli and tulshi May 4, 2022 19:36

adeinega mentioned this pull request Aug 9, 2022

Update Makefile to automatically build targets #26

Closed

FragLegs mentioned this pull request Aug 23, 2022

Supply 'aud' in the stream creation POST request #30

Open

FragLegs added 7 commits September 13, 2022 08:33

Add stream_id to SSE Framework spec as per Issue 4: #4

02d5e85

Update README with development instructions and fix error in Makefile

13b8058

Undo date change -- it is meant to be updated when spec is released

3f4d672

Regenerate the html and txt files for the sse framework

2bb86bc

Typos

4aa3c9b

Added note to PUSH/POLL section about uniqueness requirements for the…

a6c7fee

… URLs

Regenerate the html and txt files for the sse framework

93be670

FragLegs force-pushed the stream_id branch from b3b142f to 93be670 Compare September 13, 2022 13:32

tulshi reviewed Nov 17, 2022

View reviewed changes

tulshi reviewed Nov 18, 2022

View reviewed changes

Merge branch 'main' into stream_id

dc79999

FragLegs mentioned this pull request Nov 29, 2022

Should POLL URL be specified in the "delivery methods supported"? #36

Closed

FragLegs added 2 commits November 29, 2022 14:05

Respond to PR feedback

4c8dde4

Automated txt and html changes

86fa40d

topherMarie approved these changes Nov 30, 2022

View reviewed changes

FragLegs added 4 commits December 7, 2022 09:30

Fix typographical issues

29e8835

Add explanation about what an Event Stream is

bf3cc02

Autogenerate txt and html

92dfe2f

Make 'stream_id' optional in the GET request for stream configurations

9ff2c14

timcappalli reviewed Dec 8, 2022

View reviewed changes

tulshi approved these changes Dec 14, 2022

View reviewed changes

openid-sse-framework-1_0.xml Outdated Show resolved Hide resolved

FragLegs added 2 commits December 14, 2022 09:47

Address Tim's comments

81a61af

Change terms to Transmitter-Supplied and Receiver-Supplied

0f4f772

timcappalli approved these changes Jan 4, 2023

View reviewed changes

FragLegs merged commit d8b302c into main Jan 4, 2023

FragLegs deleted the stream_id branch January 4, 2023 19:52

FragLegs mentioned this pull request Jan 28, 2023

Format change #42

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Stream ID #9

Add Stream ID #9

FragLegs commented May 4, 2022 •

edited

FragLegs commented May 4, 2022

adeinega commented Aug 9, 2022

timcappalli commented Aug 29, 2022

FragLegs commented Sep 13, 2022

tulshi commented Sep 15, 2022 via email

FragLegs commented Sep 16, 2022 via email

tulshi Nov 17, 2022

FragLegs Dec 8, 2022

tulshi Nov 17, 2022

FragLegs Nov 22, 2022

tulshi Nov 17, 2022

FragLegs Nov 22, 2022

tulshi Nov 18, 2022

FragLegs Nov 29, 2022

FragLegs Nov 29, 2022

tulshi Nov 18, 2022

FragLegs Nov 29, 2022

FragLegs Nov 29, 2022

tulshi Nov 18, 2022

FragLegs Dec 7, 2022

topherMarie left a comment

topherMarie Nov 29, 2022

topherMarie Nov 29, 2022

topherMarie Nov 30, 2022

timcappalli left a comment

tulshi left a comment

timcappalli left a comment


		7.1.2.2. Updating a Stream's Status

		An Event Receiver updates the current status of a stream by making an

Add Stream ID #9

Add Stream ID #9

Conversation

FragLegs commented May 4, 2022 • edited

FragLegs commented May 4, 2022

adeinega commented Aug 9, 2022

timcappalli commented Aug 29, 2022

FragLegs commented Sep 13, 2022

tulshi commented Sep 15, 2022 via email

FragLegs commented Sep 16, 2022 via email

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

topherMarie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timcappalli left a comment

Choose a reason for hiding this comment

tulshi left a comment

Choose a reason for hiding this comment

timcappalli left a comment

Choose a reason for hiding this comment

FragLegs commented May 4, 2022 •

edited