Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extend spec with services capability #344

Merged
merged 4 commits into from
Jan 24, 2023
Merged

Extend spec with services capability #344

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0d204c1
Extend spec with services capability
achim-k Jan 17, 2023
96f5f0f
address comments
achim-k Jan 19, 2023
47e4034
spec: Use serverInfo encodings
achim-k Jan 20, 2023
7e221d2
Update docs/spec.md
achim-k Jan 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 83 additions & 1 deletion docs/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@
- [Message Data](#message-data) (binary)
- [Time](#time) (binary)
- [Parameter Values](#parameter-values) (json)
- [Advertise Services](#advertise-services) (json)
- [Unadvertise Services](#unadvertise-services) (json)
- [Service Call Response](#service-call-response) (binary)

### Sent by client

Expand All @@ -42,6 +45,7 @@
- [Set Parameters](#set-parameters) (json)
- [Subscribe Parameter Update](#subscribe-parameter-update) (json)
- [Unsubscribe Parameter Update](#unsubscribe-parameter-update) (json)
- [Service Call Request](#service-call-request) (binary)

## JSON messages

Expand All @@ -60,7 +64,8 @@ Each JSON message must be an object containing a field called `op` which identif
- `parameters`: Allow clients to get & set parameters
- `parametersSubscribe`: Allow clients to subscribe to parameter changes
- `time`: The server may publish binary [time](#time) messages
- `supportedEncodings`: array of strings | informing the client about which encodings may be used for client-side publishing. Only set if client publishing is supported.
- `services`: Allow clients to call services
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternatively, if the server never advertises a service there are no services for the client to call :)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `services`: Allow clients to call services
- `services`: Server can advertise services which clients may call

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This capability seems redundant. If a server can't advertise services, then it won't advertise any services. If it does advertise a service, why should a client make an additional check to ensure the services capability was set? And what should it do if a service is advertised, but the capability is not?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may help a client to know whether the server will potentially announce services or not. But I do not have a strong opinion on this. @jtbandes what do you think?

- `supportedEncodings`: array of strings | informing the client about which encodings may be used for client-side publishing or service call requests/responses. Only set if client publishing or services are supported.
- `metadata`: optional map of key-value pairs

#### Example
Expand Down Expand Up @@ -176,6 +181,55 @@ Informs the client about parameters. Only supported if the server declares the `
}
```

### Advertise Services

Informs the client about available services. Only supported if the server declares the `services` [capability](#server-info).

#### Fields

- `op`: string `"advertiseServices"`
- `services`: array of:
- `id`: number. The server may reuse ids when services disappear and reappear, but only if the services keeps the exact same name, type, and schema. Clients will use this unique id to cache schema info and deserialization routines.
- `name`: string
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should explain that the service name does not need to be unique. If services are uniquely named, let's drop the duplicate unique identifier id.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may happen that a service is unadvertised and a new service with the same name but different type is advertised. In this case the name is not unique.

- `type`: string
- `requestSchema`: string
- `responseSchema`: string

#### Example

```json
{
"op": "advertiseServices",
"services": [
{
"id": 1,
"name": "foo",
"type": "std_srvs/srv/Empty",
"requestSchema": "",
"responseSchema": ""
}
]
}
```

### Unadvertise Services

Informs the client about services that are no longer available. Only supported if the server declares the `services` [capability](#server-info).

#### Fields

- `op`: string `"unadvertiseServices"`
- `serviceIds`: array of number, corresponding to previous [advertisement](#advertise-services)

#### Example

```json
{
"op": "unadvertiseServices",
"serviceIds": [1, 2]
}
```

### Subscribe

- Requests that the server start streaming messages on a given topic (or topics) to the client.
Expand Down Expand Up @@ -405,3 +459,31 @@ All integer types explicitly specified (uint32, uint64, etc.) in this section ar
| ----- | ------ | ----------------------- |
| 1 | opcode | 0x02 |
| 8 | uint64 | timestamp (nanoseconds) |

#### Service Call Request

- Request to call a service that has been advertised by the server.
- Only supported if the server previously declared the `services` [capability](#server-info).

| Bytes | Type | Description |
| ----------------- | ------- | ----------------------------------------------------------------------- |
| 1 | opcode | 0x02 |
| 4 | uint32 | service id |
| 4 | uint32 | call id, a unique number to identify the corresponding service response |
| 4 | uint32 | encoding length |
| _encoding length_ | char[] | encoding, one of the encodings [supported by the server](#server-info) |
| remaining bytes | uint8[] | request payload |

### Service Call Response

- Provides the response to a previous [service call](#service-call-request).
- Only supported if the server previously declared the `services` [capability](#server-info).

| Bytes | Type | Description |
| ----------------- | ------- | ----------------------------------------------------- |
| 1 | opcode | 0x03 |
| 4 | uint32 | service id |
| 4 | uint32 | call id |
| 4 | uint32 | encoding length |
| _encoding length_ | char[] | encoding, same encoding that was used for the request |
| remaining bytes | uint8[] | response payload |