Lead Resource Type documentation

.markdownlint.yaml

@@ -0,0 +1,12 @@
+# configuration for markdownlint vscode extension
+# something is broken about yaml front-matter detection
+MD002: false
+MD041: false
+# enable long lines
+MD013: false # line-length
+# enable ordered lists indexed by letters (a, b, c)
+MD029: false
+MD033: false
+# in mdl the default is 3 spaces
+MD007: # ul-indent
+  indent: 3

.mdl_style.rb

@@ -1,3 +1,4 @@
+# configuration for mdl linter
 all
 # something is broken about yaml front-matter detection
 exclude_rule 'MD002'

content/en/docs/configuration/cloud2cloud-connector.md

@@ -96,6 +96,7 @@ plgd hub uses NATS messaging system as an event bus.
 | `clients.eventBus.nats.tls.keyFile` | string | `File name of private key in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.certFile` | string | `File name of certificate in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
+| `clients.eventBus.nats.leadResourceType.enabled` | bool | `If true, subscribe to NATS with lead resource type subject token included.` | `false` |
 
 ### GRPC Gateway Client
 

content/en/docs/configuration/cloud2cloud-gateway.md

@@ -67,6 +67,7 @@ plgd hub uses NATS messaging system as an event bus.
 | `clients.eventBus.nats.tls.keyFile` | string | `File name of private key in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.certFile` | string | `File name of certificate in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
+| `clients.eventBus.nats.leadResourceType.enabled` | bool | `If true, subscribe to NATS with lead resource type subject token included.` | `false` |
 
 ### GRPC Gateway Client
 

content/en/docs/configuration/coap-gateway.md

@@ -100,6 +100,7 @@ plgd hub uses NATS messaging system as an event bus.
 | `clients.eventBus.nats.tls.keyFile` | string | `File name of private key in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.certFile` | string | `File name of certificate in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
+| `clients.eventBus.nats.leadResourceType.enabled` | bool | `If true, subscribe to NATS with lead resource type subject token included.` | `false` |
 
 ### Identity Store Client
 

content/en/docs/configuration/grpc-gateway.md

@@ -93,6 +93,7 @@ plgd hub uses NATS messaging system as a event bus.
 | `clients.eventBus.nats.tls.keyFile` | string | `File name of private key in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.certFile` | string | `File name of certificate in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
+| `clients.eventBus.nats.leadResourceType.enabled` | bool | `If true, subscribe to NATS with lead resource type subject token included.` | `false` |
 
 ### Resource Aggregate Client
 

content/en/docs/configuration/resource-aggregate.md

@@ -70,11 +70,15 @@ plgd hub uses NATS messaging system as a event bus.
 | ---------- | -------- | -------------- | ------- |
 | `clients.eventBus.nats.url` | string | `URL to nats messaging system.` | `"nats://localhost:4222"` |
 | `clients.eventBus.nats.flusherTimeout` | string | `Define flush timeout for publishing message.` | `"30s"` |
-| `clients.eventBus.nats.jetstream`| bool | `If true, events will be published to jetstream.` | `false` |
 | `clients.eventBus.nats.tls.caPool` | []string | `File paths to the root certificates in PEM format. The file may contain multiple certificates.` |  `[]` |
 | `clients.eventBus.nats.tls.keyFile` | string | `File name of private key in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.certFile` | string | `File name of certificate in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
+| `clients.eventBus.nats.jetstream`| bool | `If true, events will be published to jetstream.` | `false` |
+| `clients.eventBus.nats.leadResourceType.enabled` | bool | `If true, publish events to NATS with lead resource type subject token included.` | `false` |
+| `clients.eventBus.nats.leadResourceType.regexFilter` | []string | `List of regex expressions used to find resouce type that will be used as the lead resource type subject for resource-level events. The expressions are iterated in order and the first matched resource type of the resource associated with the event is used in the NATS subject.` | `[]` |
+`clients.eventBus.nats.leadResourceType.filter` | string | `Can contain values "first", "last" or be kept empty (""). If "first" is used, the first resource type of the resource associated with the event will be used as the lead resource type in the NATS subject. If "last" is used, the last resource type is used in the NATS subject. If both "regexFilter" and "filter" properties are set, "regexFilter" takes precedence and "filter" is only examined if no resource type is matched by "regexFilter". If neither are set, the NATS subject will not have a lead resource type, but it will just have the "leadrt" token if the feature is enabled.` | `""` |
+| `clients.eventBus.nats.leadResourceType.useUUID` | bool | `If true then do not use the selected resource type as a token directly, but encode it into a UUID string.` | `false` |
 
 ### Event Store
 

content/en/docs/configuration/resource-directory.md

@@ -77,6 +77,7 @@ plgd hub uses NATS messaging system as a event bus.
 | `clients.eventBus.nats.tls.keyFile` | string | `File name of private key in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.certFile` | string | `File name of certificate in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
+| `clients.eventBus.nats.leadResourceType.enabled` | bool | `If true, subscribe to NATS with lead resource type subject token included.` | `false` |
 
 ### Event Store
 

content/en/docs/configuration/snippet-service.md

@@ -88,6 +88,7 @@ plgd hub uses NATS messaging system as an event bus to be notified about device
 | `clients.eventBus.nats.tls.keyFile` | string | `File name of private key in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.certFile` | string | `File name of certificate in PEM format.` | `""` |
 | `clients.eventBus.nats.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
+| `clients.eventBus.nats.leadResourceType.enabled` | bool | `If true, subscribe to NATS with lead resource type subject token included.` | `false` |
 
 ### Storage
 

content/en/docs/features/control-plane/jetstream.md

@@ -17,62 +17,6 @@ There are still some edge-cases when the plgd event couldn't be published to the
 More information about the JetStream can be found [here](https://docs.nats.io/jetstream).
 {{< /note >}}
 
-## NATS subjects overview
-
-### Definitions
-
-- `ownerID` is the owner of the device. It is calculated as `uuid.NewV5(uuid.NamespaceURL, value of JWT ownerClaim)`.
-- `deviceID` is the UUID of the device.
-- `hrefID` is the identifier of resource. It is calculated as `uuid.NewV5(uuid.NamespaceURL, href)`, where the `href` is a resource path. (eg "/oic/d").
-
-### Device events
-
-Each event is compressed by [snappy](https://github.com/google/snappy) and encoded in protobuf [devices event envelope](https://github.com/plgd-dev/hub/blob/main/resource-aggregate/cqrs/eventbus/pb/eventbus.proto). The event envelope consist of `Event.data` containing the event and `Event.event_type` describing the type of the event.
-
-#### Resource links
-
-- `plgd.owners.{ownerID}.devices.{deviceID}.resource-links.{eventType}` publishes resource-links events of types `resourcelinkspublished`, `resourcelinksunpublished`, `resourcelinkssnapshottaken` for device `deviceID` and `ownerID`
-
-#### Metadata events
-
-- `plgd.owners.{ownerID}.devices.{deviceID}.metadata.{eventType}` publishes metadata events of types `devicemetadataupdatepending`,`devicemetadataupdated`, `devicemetadatasnapshottaken` for device `deviceID` and `ownerID`
-
-#### Resources events
-
-- `plgd.owners.{ownerID}.devices.{deviceID}.resources.{hrefID}.{eventType}` publishes resources events of types `resourcechanged`, `resourcecreated`, `resourcecreatepending`, `resourcedeleted` `resourcedeletepending`, `resourceretrieved`, `resourceretrievepending`, `resourcestatesnapshottaken`, `resourceupdated`, `resourceupdatepending` for resource `hrefID`, `deviceID` and `ownerID`.
-
-### Owner events
-
-Each event is encoded in protobuf [event envelope](https://github.com/plgd-dev/hub/blob/main/authorization/pb/events.proto) and then compressed by [snappy](https://github.com/google/snappy).
-
-#### Registration events
-
-- `plgd.owners.{ownerID}.registrations.{eventType}` publishes owner events of types `devicesregistered`,`devicesunregistered` for `ownerID`.
-
-### Consumer subscriptions options
-
-For the consumers of events you can subscribe to:
-
-- `plgd.owners.>` retrieves all events of the hub.
-- `plgd.owners.{ownerId}.>` retrieves all events of the owner with the `ownerId`.
-- `plgd.owners.*.devices.{deviceId}.>` retrieves all events of the device with the `deviceId`.
-- `plgd.owners.*.devices.{deviceId}.resource-links.>` retrieves all resource link events of the device with the `deviceId`.
-- `plgd.owners.*.devices.{deviceId}.resource-links.resourcelinkspublished` retrieves the `resourcelinkspublished` event of the device with the `deviceId`.
-- `plgd.owners.*.devices.*.resource-links.>` retrieves all resource link events of all devices.
-- `plgd.owners.{ownerId}.devices.*.resource-links.>` retrieves all resource link events of all devices belonging to the owner with the `ownerId`.
-- `plgd.owners.*.devices.{deviceId}.metadata.>` retrieves all metadata events of the device with the `deviceId`.
-- `plgd.owners.*.devices.{deviceId}.metadata.devicemetadataupdated` retrieves the `devicemetadataupdated` event of the device with the `deviceId`.
-- `plgd.owners.*.devices.*.metadata.>` retrieves all metadata events of all devices.
-- `plgd.owners.{ownerId}.devices.*.metadata.>` retrieves all metadata events of all devices belonging to the owner with the `ownerId`.
-- `plgd.owners.*.devices.{deviceId}.resources.>` retrieves all resource events of the device with the `deviceId`.
-- `plgd.owners.*.devices.{deviceId}.resources.{hrefId}.>` retrieves all events of the resource with the `hrefId` for the device with the `deviceId`.
-- `plgd.owners.*.devices.{deviceId}.resources.{hrefId}.resourcechanged` retrieves the `resourcechanged` events of the resource with the `hrefId` for the device with the `deviceId`.
-- `plgd.owners.*.devices.{deviceId}.resources.*.resourcechanged` retrieves the `resourcechanged` events of all resources for the device with the `deviceId`.
-- `plgd.owners.*.devices.*.resources.*.resourcechanged` retrieves the `resourcechanged` events of all resources for all devices.
-- `plgd.owners.*.devices.*.resources.{hrefId}.resourcechanged` retrieves the `resourcechanged` events of the resource with the `hrefId` for all devices.
-- `plgd.owners.{ownerId}.devices.*.resources.*.resourcechanged` retrieves the `resourcechanged` events of all resources for all devices belonging to the owner with the `ownerId`.
-- `plgd.owners.{ownerId}.devices.*.resources.{hrefId}.resourcechanged` retrieves the `resourcechanged` events of the resource with the `hrefId` for all devices belonging to the owner with the `ownerId`.
-
 ## Enable JetStream
 
 {{< note >}}