Skip to content

Commit

Permalink
rpcri: rework to uniquely match either methods or signals
Browse files Browse the repository at this point in the history 
This changes RPC RI to only two variants. Only `PATH:METHOD:SIGNAL` and
`PATH:METHOD` is allowed. The signal matching variant no longer matches
its associated method and vice-versa.
  • Loading branch information
@Cynerd
Cynerd committed Jul 22, 2024
1 parent d49b9a1 commit 7159acf
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 61 deletions.
20 changes: 10 additions & 10 deletions src/rpcmethods/broker.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,12 +59,12 @@ subscribes on given method in all accessible nodes of the broker.
|--------------------------|--------|
| String \| \[String, Int] | Bool |

The parameter is [resource identifier](../rpcri.md) that is used to match
signals. There is also an option to subscribe only for limited time by using
list parameter where first argument is RPC RI and the second is TTL in seconds.
The subscribe with specified TTL is automatically dropped when given number of
seconds elapses. This time can be extended by calling `subscribe` with TTL again
or it can be even removed when called without TTL.
The parameter is [resource identifier for signals](../rpcri.md). There is also
an option to subscribe only for limited time by using list parameter where first
argument is RPC RI and the second is TTL in seconds. The subscribe with
specified TTL is automatically dropped when given number of seconds elapses.
This time can be extended by calling `subscribe` with TTL again or it can be
even removed when called without TTL.

It provides `true` if subscription was added and `false` if there was already
such subscription.
Expand All @@ -90,8 +90,8 @@ Reverts an operation of `.broker/currentClient:subscribe`.
|-----------|--------|
| String | Bool |

The parameter must [resource identifier](../rpcri.md) used for subscription
creation.
The parameter must be [resource identifier for signal](../rpcri.md) used for
subscription creation.

It provides `true` in case subscription was removed and `false` if it couldn't
have been found.
Expand All @@ -118,8 +118,8 @@ client.
|-----------|---------------|
| Null | [String, ...] |

List of strings is provided where strings are [resource identifiers](../rpcri.md)
for the existing subscriptions.
List of strings is provided where strings are [resource identifiers for
signals](../rpcri.md) for the existing subscriptions.

```
=> <id:42, method:"subscriptions", path:".broker/currentClient">i{}
Expand Down
73 changes: 22 additions & 51 deletions src/rpcri.md
View file
Original file line number Diff line number Diff line change
@@ -1,68 +1,39 @@
# SHV RPC RI

This is definition of Resource Identifiers for SHV RPC. SHV has two types of
resources; those are methods and signals. Signals are always associated with
some method and thus Resource Identifier actually matches primarily methods
while it can also select between different signals.
resources; those are methods and signals.

Resource identifiers are human readable and are used thorough this
documentation, in the broker's signal filtering. They can also be used by other
tools.
documentation as well as in the broker's signal filtering. They can also be used
by other tools.

Example of Resource Identifiers for SHV RPC:
```
.app:name
test/device/track/1:*:chng
test/*:ls:lschng
```

Resource Identifier consists of up to triplet delimited by colon `:`. The
following variations are allowed:

```
PATH
PATH:METHOD
PATH:METHOD:SIGNAL
PATH:METHOD:
```
The format is either `PATH:METHOD` for methods or `PATH:METHOD:SIGNAL` for
signals.

__The first field `PATH` is the SHV path.__ It can be glob pattern (rules from
POSIX.2, 3.13 with added support for ``**`` that matches multiple nodes). Note
that empty `PATH` is the root of the SHV node tree.

__The second field `METHOD` is the SHV RPC method name.__ It can be wildcard
pattern (rules from POSIX.2, 3.13). The method name can't be empty. It is
assumed to be `*` if not specified at all (the `PATH` variation).

__The third field `SIGNAL` is the SHV RPC signal name__ while `METHOD` in such
case is its source. It can be wildcard pattern (rules from POSIX.2, 3.13). It is
assumed to be `*` if not specified (the `PATH` and `PATH:METHOD` variant). The
empty signal name is invalid and thus it is used to identify only method (thus
`PATH:METHOD:` matches only method while `PATH:METHOD` matches also all of its
signals).
pattern (rules from POSIX.2, 3.13). The empty method name is invalid and thus is
invalid pattern.

The following table breaks down different variations and how they are applied
when matching either method or signal:
__The third field `SIGNAL` that is used only for signals is the SHV RPC signal
name__ while `METHOD` in such case is its source. It can be wildcard pattern
(rules from POSIX.2, 3.13). The empty signal name is invalid and thus is invalid
pattern.

| Variation | Method | Signal |
|----------------------|-----------------------------------------------|-------------------------------------------------------------|
| `PATH` | Applies if `PATH` matches. | Applies if `PATH` matches. |
| `PATH:METHOD` | Applies if `PATH` and `METHOD` matches. | Applies if `PATH` and `METHOD` matches. |
| `PATH:METHOD:SIGNAL` | Applies if `PATH` and `METHOD` matches. | Applies if `PATH` and `METHOD` and `SIGNAL` matches. |
| `PATH:METHOD:` | Applies if `PATH` and `METHOD` matches. | Never applies |
The examples of Resource Identifiers for methods and method matching:

Notice that there is no variation that matches only signals and not its
associated method. This is because signal is always associated with some method
and Resource Identifier primarily identifies the method and only after that
filters its signals if resource is signal. This means that Resource Identifier
can't be used to filter both methods and signals from the same set of resources.
| Resource | `**:*` | `**:get` | `test/**` | `test/**:get:*chng` |
|------------------------------------------------------------------|--------|-----------|-----------|---------------------|
| Method `name` on path `.app` | ✔️ | ❌ | ❌ | ❌ |
| Method `get` on path `sub/device/track` | ✔️ | ✔️ | ❌ | ❌ |
| Method `get` on path `test/device/track` | ✔️ | ✔️ | ✔️ | ✔️ |

The examples of different Resource Identifiers and resources:
The examples of Resource Identifiers for signals and signals matching:

| Resource | `**` | `**:get:` | `test/**` | `test/**:get:*chng` |
|------------------------------------------------------------------|------|-----------|-----------|---------------------|
| Method `name` on path `.app` | ✔️ | ❌ | ❌ | ❌ |
| Method `get` on path `sub/device/track` | ✔️ | ✔️ | ❌ | ❌ |
| Method `get` on path `test/device/track` | ✔️ | ✔️ | ✔️ | ✔️ |
| Signal `chng` associated with `get` on path `test/device/track` | ✔️ | ❌ | ✔️ | ✔️ |
| Signal `lschng` associated with `ls` on path `test/device/track` | ✔️ | ❌ | ✔️ | ❌ |
| Resource | `**:*:*` | `**:get:*` | `test/**:get:*chng` | `test/*:ls:lsmod` |
|------------------------------------------------------------------|----------|------------|---------------------|-------------------|
| Signal `chng` associated with `get` on path `test/device/track` | ✔️ | ✔️ | ✔️ | ❌ |
| Signal `lschng` associated with `ls` on path `test/device/track` | ✔️ | ❌ | ❌ | ✔️ |

0 comments on commit 7159acf

Please sign in to comment.