Notification compliance #53

stroncoso-quobis · 2024-10-24T13:43:48Z

What type of PR is this?

Add one of the following kinds:

enhancement/feature

What this PR does / why we need it:

This PR is needed to have an event notification system compliant with the CAMARA framework and also to grant async event communications that are inherent for the WebRTC call use cases.

Which issue(s) this PR fixes:

Fixes #15

Special notes for reviewers:

n/a

Changelog input

 release-note
- Fix notification system granting explicit subscription for sessions and registrations.
- Updated UML documentation
- Included callback for Registration and Session handling

Additional documentation

UML must be updated within this PR.
A dedicated websocket use case must be explained on Conlfuence or at supporting documentation

stroncoso-quobis · 2024-11-08T18:33:13Z

Hi team,

Good news, PR is ready for a first review.

Main elements to consider:

API works based on two kind of susbcriptions: registration and session. One is designed to keep the device reachable, and the other to track a session in progress.
regsitration
- Event when the network requires to refresh register
- Event when a new session is requested (incoming call)
session
- Event to update and define participants on the call
- Event to update session status (ringing, progressing, accepting, cancel, cleared, …)
- Event to update SDP information (new candidates, network updates, track bw update, ...)

Use a Swagger rendered view appending https://editor.swagger.io/?url= to the RAW commint file.

https://editor.swagger.io/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fcamaraproject%2FWebRTC%2Fdc87f0cb305a8fdc37d8c33ce0f8b0508ea49e5e%2Fcode%2FAPI_definitions%2FBYON-Webrtc-Events.yaml

The file is big, I know, so I will track your attention to:

Initial description, check texts and provide comments about general approach
SubscriptionRequest schema: It is the payload for a new subscription
- registration event subscription requires a the subscriber information, while session event subscription requires both, the user information and the sessionId to subscribe to.
- Have in mind that, per CloudEvents+CAMARA specs, our WebRTC details are included into SubscriptionDetail that is included into config.
CloudEvent schema: It is the payload of the event received for any case
- Our WebRTC relevant information is placed into the data property that could be one of the two possible events: EventRegistration and EventSession.
- The SubscriptionEnds event is a CAMARA requirement
EventRegistration schema: Brand new object
- To inform about re-registration or a new incomming session.
- Tries to map to the BYON-RACM session info, but including an optional new session structure (call incoming)
- Included a hook for future branded calls with a subject field
EventSession: Event about session updates
- It is mapped to the vvoipSessionInformation schema of the BYON-CallHandling API
- Tries to unify a couple of duplicated schemas like the SubscriberUser info or the SDP descriptor

Please, @deepakjaiswal1 , share with your team and provide some feedback, while I clean the linter errors and try to create some documentation for this update (workflows are not valida anymore) and document some bugs detected on other files.

Best regards,

stroncoso-quobis · 2024-11-12T11:51:52Z

Hi all,

An update about today's commit. I fixed all linter errors and also reviewed the examples for a better comprehension of the events. Reviewing the examples, I found that sessionId was missing on the new_session_event, so I included it as part of the EventRegistration / sessionRequest . Without it, it is not possible to grant a valid suscription for session events.

Waiting for comments and reviews

rartych · 2024-11-19T13:54:05Z

code/API_definitions/BYON-Webrtc-Events.yaml

+  description: Product documentation at CAMARA
+  url: https://github.com/camaraproject/
+servers:
+  - url: "{apiRoot}/webrtc-events/v1"


According to https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#53-api-versions-throughout-the-release-process
the url should end with vwip

Suggested change

- url: "{apiRoot}/webrtc-events/v1"

- url: "{apiRoot}/webrtc-events/vwip"

When the release is prepared it should be changed to {apiRoot}/webrtc-events/v0.1rc and finally to {apiRoot}/webrtc-events/v0.1
https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#52-api-version-in-url-oas-servers-object

rartych · 2024-11-19T13:54:48Z

code/API_definitions/BYON-Webrtc-Events.yaml

+      apiRoot:
+        default: http://localhost:9091
+        description: API root
+      deviceId:


deviceId is not used in url above

code/API_definitions/BYON-Webrtc-Events.yaml

rartych · 2024-11-19T14:02:25Z

According to https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#resource-based-explicit-subscription

type must follow the format: org.camaraproject... with the api-version with letter v and the major version

Then the event types should be like (with v0 inserted):
org.camaraproject.webrtc-events.v0.session
org.camaraproject.webrtc-events.v0.registration

rartych · 2024-11-19T14:07:12Z

code/API_definitions/BYON-Webrtc-Events.yaml

+        msisdn:
+          type: string
+          description: The MSISDN is the mapping of the telephone number to the subscriber identity module in a mobile or cellular phone system. A unique identifier on the network to this subscriber.


CAMARA recommends to avoid Telco specific names and suggest to use phoneNumber instead of MSISDN - https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml

PhoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. type: string pattern: '^\+[1-9][0-9]{4,14}$' example: "+123456789"

Agree, I also found that after push the PR. I will change it on next commits.

rartych · 2024-11-19T14:13:11Z

code/API_definitions/BYON-Webrtc-Events.yaml

+        sessionRequest:
+          description: Object present only when receiving a new session request
+          type: object
+          properties:


Is subscriptionId missing here?

rartych · 2024-11-19T14:14:29Z

code/API_definitions/BYON-Webrtc-Events.yaml

+      required:
+        - vvoipSessionID
+      type: object
+      properties:


Is subscriptionId missing here?

subscriptionId included as per comms 4.0 -> https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification

rartych · 2024-11-19T14:17:51Z

code/API_definitions/BYON-Webrtc-Events.yaml

+        - $ref: "#/components/parameters/x-correlator"
+      security:
+        - openId:
+            - api-name:read


https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#1161-scope-naming

Suggested change

- api-name:read

- webrtc-events-subscriptions:read

In fact, it should include one of each, isn't it? I mean, if I'm not wrong, to have a valid GET reponse you need one of these permissions, one for each type of subscription.

org.camaraproject.webrtc-events.session-status:read

org.camaraproject.webrtc-events.session-invitation:read

🤔

I have changed the suggestion according to:
https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#apis-which-deal-with-explicit-subscriptions

Scopes should be represented as below for APIs that offer explicit event subscriptions with action read and delete, for example:

API Name: device-roaming-subscriptions

Grant-level, action on resource: read, delete

results in scope: device-roaming-subscriptions:read. This type of formulation is not used for the creation action.

The format to define scopes for explicit subscriptions with action creation, includes the event type in its formulation to ensure that consent is managed at the level of subscribed event types.

- Renamed event types - Removed atomic schemas - Reviewed descriptions

- Change event types to include API version v0 - Reviewed descriptions for requests and examples - Resolved linter errors - Uniform schemas: Event_sufix and vvoipSessionInformation - Improved type definitions for VvoipSesisonId

stroncoso-quobis · 2024-12-10T10:51:38Z

Hi team,

Big update following latest meeting agreements:

Commonalities:
- Added v0 to type events
- Solved linter errors abstracting the class of data object for CloudEvents (removed oneOf)
- Uniform schema naming: EventSessionStatus, EventSessionInvitation and EventSubscriptionEnds
Voice video info:
- Renamed the data content of API-specific events to VvoipSessionInformation to grant same naming for all three APIs: RACM, CallHandling and webrtc-events
- Description and examples reviews to fit schemas and describe actions in progress

Please, @rartych and @deepakjaiswal1 , if you can review and approve or provide comments it will be great.
Any other group participant, feel free to provide feedback.

Best regards,

rartych · 2024-12-16T18:52:58Z

code/API_definitions/BYON-Webrtc-Events.yaml

+      operationId: retrieveNotificationChannelSubscription
+      security:
+        - openId:
+            - api-name:read


Suggested change

- api-name:read

- webrtc-events-subscriptions:read

rartych · 2024-12-16T18:53:28Z

code/API_definitions/BYON-Webrtc-Events.yaml

+      description: delete a given webrtc-events subscription.
+      security:
+        - openId:
+            - api-name:delete


Suggested change

- api-name:delete

- webrtc-events-subscriptions:delete

teikuran · 2024-12-10T13:22:39Z

code/API_definitions/BYON-Webrtc-Events.yaml

+            Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided
+             at API project level.


https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#subscriptions-data-model
About the Note, for the clarity, Note: As of now only one value MUST passed. Use of multiple value will be decided following meta-release at API project level. how is this?

stroncoso-quobis force-pushed the feat/notification-service branch from e83fc8a to 72d67fa Compare October 25, 2024 16:53

feat(api): Included new webrtc-events explicit subscription

dc87f0c

stroncoso-quobis force-pushed the feat/notification-service branch from 72d67fa to dc87f0c Compare November 8, 2024 18:10

stroncoso-quobis requested a review from deepakjaiswal1 November 8, 2024 18:29

stroncoso-quobis marked this pull request as ready for review November 8, 2024 18:40

stroncoso-quobis requested review from sushanthmavenir and pradeepachar-mavenir as code owners November 8, 2024 18:40

stroncoso-quobis added 2 commits November 8, 2024 19:43

fix(api): Review trailing spaces for webrtc-events API

a05ca6d

fix(api): SessionID incl on NEW_SESSION_INCOMING and linter fix

eae43b7

stroncoso-quobis force-pushed the feat/notification-service branch from 682eba7 to eae43b7 Compare November 12, 2024 11:46

rartych reviewed Nov 19, 2024

View reviewed changes

code/API_definitions/BYON-Webrtc-Events.yaml Outdated Show resolved Hide resolved

rartych reviewed Nov 19, 2024

View reviewed changes

fix(api): Removed not supported protocols (MQTT, AMQP, NATS, KAFKA)

a65545d

stroncoso-quobis force-pushed the feat/notification-service branch from e22fd79 to a65545d Compare November 19, 2024 14:56

fix(api): Simplified events

b2ecfd3

- Renamed event types - Removed atomic schemas - Reviewed descriptions

stroncoso-quobis force-pushed the feat/notification-service branch from 2be6276 to b2ecfd3 Compare December 3, 2024 14:39

stroncoso-quobis added 2 commits December 3, 2024 15:53

fix(api): comms compliance: server params and subscriptionId

248e056

fix(webrtc-events): Fixed examples and polyform SessionEvent

db6cd15

stroncoso-quobis force-pushed the feat/notification-service branch from a89a07c to db6cd15 Compare December 9, 2024 11:15

stroncoso-quobis mentioned this pull request Dec 11, 2024

feat(callhandling): VvoipSessionInformation schema reviewed #56

Open

stroncoso-quobis self-assigned this Dec 11, 2024

rartych reviewed Dec 16, 2024

View reviewed changes

teikuran reviewed Dec 17, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Notification compliance #53

Notification compliance #53

stroncoso-quobis commented Oct 24, 2024 •

edited

Loading

stroncoso-quobis commented Nov 8, 2024

stroncoso-quobis commented Nov 12, 2024

rartych Nov 19, 2024

rartych Nov 19, 2024

rartych commented Nov 19, 2024

rartych Nov 19, 2024

stroncoso-quobis Nov 19, 2024

rartych Nov 19, 2024

rartych Nov 19, 2024

stroncoso-quobis Dec 3, 2024

rartych Nov 19, 2024 •

edited

Loading

stroncoso-quobis Dec 3, 2024

rartych Dec 16, 2024

stroncoso-quobis commented Dec 10, 2024

rartych Dec 16, 2024

rartych Dec 16, 2024

teikuran Dec 10, 2024

	- url: "{apiRoot}/webrtc-events/v1"
	- url: "{apiRoot}/webrtc-events/vwip"

		Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided
		at API project level.

Notification compliance #53

Are you sure you want to change the base?

Notification compliance #53

Conversation

stroncoso-quobis commented Oct 24, 2024 • edited Loading

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for reviewers:

Changelog input

Additional documentation

stroncoso-quobis commented Nov 8, 2024

stroncoso-quobis commented Nov 12, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rartych commented Nov 19, 2024

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

rartych Nov 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stroncoso-quobis commented Dec 10, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stroncoso-quobis commented Oct 24, 2024 •

edited

Loading

rartych Nov 19, 2024 •

edited

Loading