Simplify flow diagrams

[acoburn]

This simplifies the flow diagrams, removing those actors that are out of scope for this specification and placing the common portions of the flow into its own diagram. And given that source and target are not defined until later in the document, this uses more generally understood terminology to describe the categories of interaction.

PR towards https://github.com/solid/notifications/issues/77

[elf-pavlik]

I think separating

• Subscription Flow
• Notifications Flow

into separate diagrams is very helpful!

We could include Unsubscribe on the Subscription Flow and just put a marker where the Notification Flow fits in, detailed in separate diagram.

[elf-pavlik]

Another option:

sequenceDiagram
  autonumber
  participant Notifications Target
  participant Subscriber
  participant Storage Description Resource
  participant Subscription Resource

  Subscriber ->> Storage Description Resource: Discovery
  Storage Description Resource ->> Subscriber: Storage Description Resource
  Subscriber ->> Subscription Resource: Request subscription (with access token)
  Subscription Resource ->> Subscriber: Subscription response (with subscription information)

  alt pick-up
    Subscriber ->> Notifications Source: Establish connection
    Notifications Source -->> Subscriber: Stream notifications
  else delivery
    loop for each notification
      Notifications Source ->> Notifications Target: Deliver notification
      Notifications Target ->> Notifications Source: 200 OK
    end
  end

  Subscriber ->> Subscription Resource: Unsubscribe (delete subscription)
  Subscription Resource ->> Subscriber: 204 No Content

[elf-pavlik]

I think separate

• Subscription Flow (with Unsubscribe)
• Notification Flow

Would be the cleanest approach.

sequenceDiagram
  autonumber
  participant Subscriber
  participant Storage Description Resource
  participant Subscription Resource

  Subscriber ->> Storage Description Resource: Discovery
  Storage Description Resource ->> Subscriber: Storage Description Resource
  Subscriber ->> Subscription Resource: Subscription Request (with access token)
  Subscription Resource ->> Subscriber: Subscription Response (with subscription information)

  Note over Subscriber, Subscription Resource: Notifications Flow

  Subscriber ->> Subscription Resource: Unsubscribe (delete subscription)
  Subscription Resource ->> Subscriber: 204 No Content

sequenceDiagram
  autonumber
  participant Subscriber
  participant Notifications Source

  Subscriber ->> Notifications Source: Establish connection
  Notifications Source -->> Subscriber: Stream notifications

sequenceDiagram
  autonumber
  participant Notifications Target
  participant Notifications Publisher

  loop for each notification
    Notifications Publisher ->> Notifications Target: Deliver notification
    Notifications Target ->> Notifications Publisher: 200 OK
  end

In the implementation I'm working on, which implements the subscriber part, I have separate background job queues for subscribing and handing incoming notifications. There are separate workers handling subscriptions and notifications which could eventually run as independent microservices.

[elf-pavlik]

I think we should add an inline issue referencing #106 and once it gets resolved update all affected naming.

[acoburn]

@elf-pavlik I have updated the diagrams and terminology to be in line with what was discussed in the 10 Nov meeting

[elf-pavlik]

Just want to note that publishing may be generally associated with publishing (and serving) a document on a Web site.

Besides publishing the notifications, the publisher also publishes the topic to which subscriber wants to subscribe to.

I'm open to further iterations on the terminology and fully agree that this PR as it stands makes a good step forward.

[csarven]

Besides publishing the notifications, the publisher also publishes the topic to which subscriber wants to subscribe to.

I don't quite follow the context of that sentence. What's the significance of "topic" besides it being a unit of information in the subscription request payload? Is the "publisher" intended to manage the "topic" resource that's of interest to the subscriber? As I understand it, the "publisher" is a role of creating/producing/sending/delivering/distributing a notification, and that the publication/having a representation of the topic resource is done by some resource server.

[elf-pavlik]

As I understand it, the "publisher" is a role of creating/producing/sending/delivering/distributing a notification, and that the publication/having a representation of the topic resource is done by some resource server.

How publisher is deploying there services is out of scope. Still both the resource which is referenced as the topic of the subscription and the party which is delivering notifications to the target, or providing the notifications source, are working together. Since we don't define any details how the resource server and the notifying party are working together, they could be part of the same application or separate services using implementation specific way of communicating. Actually the subscription manager could also be a separate service which coordinates with other two mentioned roles. This way we have 3 distinct responsibilities under a single umbrella of the publisher:

• resource server hosting the topic
• subscription manager - we define how subscriber can discover it
• notifying party - we only define how subscriber either fetches notifications for source or exposes target to which notifications get delivered

This conversation should leave this PR BTW so that we can close it.

[csarven]

The context of the interaction here is specifically about a sender delivering a notification to a target. I have no objection to using umbrella terms when necessary, and not in place of more specific terms. I want to know if you have an objection to using sender so we can close the PR.

[csarven]

Shouldn't the resource that advertises the discovery (notification channel) resource be included in the diagram in https://solid.github.io/notifications/protocol#solid-notifications-flow-protocol ?