Skip to content

Commit 5c8883e

Browse files
xuzhenbaoxuzhenbao
committed
Improve doc for RSA
1 parent c6c9913 commit 5c8883e

23 files changed

+816
-323
lines changed

‎bundles/remote_services/README.md‎

Lines changed: 32 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -33,26 +33,25 @@ The topology manager decides which services should be imported and exported acco
3333

3434
### Remote Service Admin
3535

36-
The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.
36+
The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.
3737

38-
#### Endpoints and proxies
38+
#### Remote Service Admin DFI
3939

40-
To delegate a *received* method call to the actual service implementation, the RSA uses an "endpoint" bundle, which has all the knowledge about the marshalling and unmarshalling of data for the service. This endpoint bundle is specific to the used RSA implementation, and as such cannot be reused between various RSA implementations.
40+
Provides remote service admin using HTTP and JSON. The serialization is done using [libdfi](../../libs/dfi/README.md) to convert function call information into [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson).
41+
`libffi` is configured using descriptor files in the bundles.
4142

42-
Invoking a *remote* method is done by using "proxy" bundles. Similar as to endpoints, proxy bundles encapsulate all knowledge to marshall and unmarshall data for a remote method call and as such can not be shared between RSA implementations.
43-
44-
Both proxy and endpoint bundles are loaded on demand when a service is imported or exported by the RSA. As such, these bundles **must** not be added to the list of "auto started" bundles, but placed in a separate location. By default, `endpoints` is used as location for locating proxy and/or endpoint bundles.
45-
46-
Note that since endpoints and proxies need to be created manually, one has full control about the handling of specifics of marshalling and unmarshalling data and dealing with exceptions.
43+
| **Bundle** | `rsa_dfi.zip` |
44+
|--|--|
45+
| **Configuration** | See [Remote Service Admin DFI](remote_service_admin_dfi/README.md) |
4746

48-
#### HTTP/JSON
47+
#### Remote Service Admin SHM
4948

50-
Provides a RSA implementation that uses JSON to marshal requests and HTTP as transport mechanism for its remote method invocation. It is compatible with the *Remote Service Admin HTTP* implementation provided by [Amdatu Remote](https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote).
49+
Provides remote service admin using shared memory. The serialization implementation is pluggable, and the default serialization is done using [libdfi](../../libs/dfi/README.md) to convert function call information into [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson).
50+
`libffi` is configured using descriptor files in the bundles.
5151

52-
| **Bundle** | `remote_service_admin_http.zip` |
53-
|--|--|
54-
| **Configuration** | `RSA_PORT`: defines the port on which the HTTP server should listen for incoming requests. Defaults to port `8888`; |
55-
| | `ENDPOINTS`: defines the location in which service endpoints and/or proxies can be found. Defaults to `endpoints` in the current working directory |
52+
| **Bundle** | `rsa_shm.zip` |
53+
|-------------------|------------------------------------------------------------------------|
54+
| **Configuration** | See [Remote Service Admin SHM](remote_service_admin_shm_v2/README.md) |
5655

5756
### Discovery
5857

@@ -72,15 +71,22 @@ Provides a service discovery with preconfigured discovery endpoints, allowing a
7271

7372
Note that for configured discovery, the "Endpoint Description Extender" XML format defined in the OSGi Remote Service Admin specification (section 122.8 of OSGi Enterprise 5.0.0) is used.
7473

75-
See [etcd discovery](discovery_etcd/README.md)
76-
7774
#### etcd discovery
7875

76+
Provides a service discovery using etcd distributed key/value store.
77+
7978
| **Bundle** | `discovery_etcd.zip` |
79+
|------------|----------------------|
80+
| **Configuration** | See [etcd discovery](discovery_etcd/README.md)|
8081

81-
Provides a service discovery using etcd distributed key/value store.
82+
#### Zero configuration discovery
83+
84+
Provides a service discovery using zeroconf (Bonjour).
85+
86+
| **Bundle** | `rsa_discovery_zeroconf.zip` |
87+
|--|----------------------------|
88+
| **Configuration** | See [Zeroconf Discovery](discovery_zeroconf/README.md) |
8289

83-
See [etcd discovery](discovery_etcd/README.md)
8490

8591
## Usage
8692

@@ -129,26 +135,27 @@ Note that the `RSA_PORT` property needs to be unique for at least the client in
129135

130136
## Building
131137

132-
To build the Remote Service Admin Service the CMake build option "`BUILD_REMOTE_SERVICE_ADMIN`" has to be enabled.
138+
To build the Remote Service Admin Service the CMake build option "`BUILD_REMOTE_SERVICE_ADMIN`" has to be enabled.If you use conan to build it, you should set the conan option `celix:build_remote_service_admin` to true.
133139

134140
## Dependencies
135141

136142
The Remote Service Admin Service depends on the following subprojects:
137143

138144
- Framework
139145
- Utils
146+
- dfi
147+
- log_helper
140148

141-
Also the following libraries are required for building and/or using the Remote Service Admin Service subproject:
142-
143-
- Jansson (build and runtime)
144-
- cURL (build and runtime)
145149

146150
## RSA Bundles
147151

148-
* [Remote Service Admin DFI](remote_service_admin_dfi) - A Dynamic Function Interface (DFI) implementation of the RSA.
149-
* [Topology Manager](topology_manager) - A (scoped) RSA Topology Manager implementation.
152+
* [Remote Service Admin DFI](remote_service_admin_dfi/README.md) - A Dynamic Function Interface (DFI) implementation of the RSA.
153+
* [Remote Service Admin SHM](remote_service_admin_shm_v2/README.md) - A Shared Memory (SHM) implementation of the RSA.
154+
* [Remote Service Admin RPC Using JSON](rsa_rpc_json/README.md) - A Remote Procedure Call (RPC) implementation of the RSA using JSON.
155+
* [Topology Manager](topology_manager/README.md) - A (scoped) RSA Topology Manager implementation.
150156
* [Discovery Configured](discovery_configured) - A RSA Discovery implementation using static configuration (xml).
151157
* [Discovery Etcd](discovery_etcd/README.md) - A RSA Discovery implementation using etcd.
158+
* [Discovery Zeroconf](discovery_zeroconf/README.md) - A RSA Discovery implementation using Bonjour.
152159

153160

154161
## Notes

‎bundles/remote_services/discovery_zeroconf/README.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: Discovery Zeroconf
3+
---
4+
5+
<!--
6+
Licensed to the Apache Software Foundation (ASF) under one or more
7+
contributor license agreements. See the NOTICE file distributed with
8+
this work for additional information regarding copyright ownership.
9+
The ASF licenses this file to You under the Apache License, Version 2.0
10+
(the "License"); you may not use this file except in compliance with
11+
the License. You may obtain a copy of the License at
12+
13+
http://www.apache.org/licenses/LICENSE-2.0
14+
15+
Unless required by applicable law or agreed to in writing, software
16+
distributed under the License is distributed on an "AS IS" BASIS,
17+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18+
See the License for the specific language governing permissions and
19+
limitations under the License.
20+
-->
21+
22+
## Discovery Zeroconf
23+
24+
The `Discovery_zeroconf` is implemented based on mDNS, and its operation depends on the mDNS daemon.
25+
26+
The mapping between celix and mdns services is as follows:
27+
28+
| **mDNS service** | **celix service** |
29+
|------------------|-------------------------------------------|
30+
| instance name | service name+hash(endpoint uuid) |
31+
| service type | "_celix-rpc._udp"+${custom subtype} |
32+
| domain name | "local" |
33+
| txt record | service properties |
34+
| host | "celix_rpc_dumb_host.local."(It is dummy) |
35+
| port | 50009(It is dummy) |
36+
37+
38+
Because We will perform the mDNS query only using link-local multicast, so we set domain name default value "local".
39+
40+
To reduce the operation of conversion between host name and address info. we set the address info to txt record, and set a dummy value("celix_rpc_dumb_host.local." and "50009") to the host name and port.
41+
42+
We set the instance name of the mDNS service as `service_name + hash(endpoint uuid)`. If there is a conflict in the instance name, mDNS_daemon will resolve it. Since the maximum size of the mDNS service instance name is 64 bytes, we take the hash of the endpoint uuid here, which also reduces the probability of instance name conflicts.
43+
44+
According to [rfc6763](https://www.rfc-editor.org/rfc/rfc6763.txt) 6.1 and 6.2 section, DNS TXT record can be up to 65535 (0xFFFF) bytes long in mDNS message. and we should keep the size of the TXT record under 1300 bytes(allowing it to fit in a single 1500-byte Ethernet packet). Therefore, `Discovery_zeroconf` announce celix service endpoint using multiple txt records and each txt record max size is 1300 bytes.
45+
46+
### Supported Platform
47+
- Linux
48+
49+
### Conan Option
50+
build_rsa_discovery_zeroconf=True Default is False
51+
52+
### CMake Option
53+
RSA_DISCOVERY_ZEROCONF=ON Default is OFF
54+
55+
### Software Design
56+
57+
#### The Remote Service Endpoint Announce Process
58+
59+
In the process of publishing remote service endpoints, `discovery_zeroconf` provides an `endpoint_listener_t` service, and sets the service property `DISCOVERY=true`. `topology_manager` updates service endpoint description to `discovery_zeroconf` by calling this service. At the same time, `discovery_zeroconf` establishes a domain socket connection with `mDNS_daemon`, and `discovery_zeroconf` publishes the service information to mDNS_daemon through this connection. Then, `mDNS_daemon` publishes the service information to other `mDNS_daemons`. The sequence diagram is as follows:
60+
61+
![remote_service_endpoint_announce_process](diagrams/service_announce_seq.png)
62+
63+
#### The Remote Service Endpoint Discovery Process
64+
65+
In the process of discovering remote service endpoints, discovery_zeroconf also establishes a domain socket connection with mDNS_daemon. discovery_zeroconf listens to remote endpoint information through this connection, and updates the listened remote endpoint information to topology_manager. The sequence diagram is as follows:
66+
67+
![remote_service_endpoint_discovery_process](diagrams/service_discovery_seq.png)
68+
69+
### Example
70+
71+
See the cmake target `remote-services-zeroconf-server` and `remote-services-zeroconf-client`.
72+
73+
**Notes:** Before running the example, you should start the [mDNS](https://github.com/apple-oss-distributions/mDNSResponder) daemon first.

‎bundles/remote_services/discovery_zeroconf/diagrams/service_announce_seq.png‎

44.1 KB
Loading

‎bundles/remote_services/discovery_zeroconf/diagrams/service_announce_seq.puml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
Licensed to the Apache Software Foundation (ASF) under one or more
2+
contributor license agreements. See the NOTICE file distributed with
3+
this work for additional information regarding copyright ownership.
4+
The ASF licenses this file to You under the Apache License, Version 2.0
5+
(the "License"); you may not use this file except in compliance with
6+
the License. You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
16+
@startuml
17+
18+
box server process
19+
participant Announcer
20+
control AnnouncerThread
21+
participant Fw
22+
participant mDNS_daemon
23+
end box
24+
Announcer->Fw:register endpoint listener service
25+
create AnnouncerThread
26+
Announcer ->AnnouncerThread:
27+
==setup==
28+
--\Announcer: add endpoint\n (use endpoint listener service)
29+
loop
30+
alt mDNS server disconnect
31+
AnnouncerThread->mDNS_daemon:DNSServiceCreateConnection
32+
return DNSServiceRef
33+
end alt
34+
35+
alt Have new endpoint
36+
AnnouncerThread->AnnouncerThread:Converting endpoint properties to txt records(max 1300 bytes)
37+
AnnouncerThread->mDNS_daemon:DNSServiceRegister(DNSServiceRef,instanceName, txtRecord ...)
38+
return registerRef
39+
loop Have more endpoint properties
40+
AnnouncerThread->mDNS_daemon:DNSServiceAddRecord(registerRef, txtRecord ...)
41+
end loop
42+
end alt
43+
end loop
44+
45+
@enduml

‎bundles/remote_services/discovery_zeroconf/diagrams/service_discovery_seq.png‎

56.5 KB
Loading

‎bundles/remote_services/discovery_zeroconf/diagrams/service_discovery_seq.puml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
Licensed to the Apache Software Foundation (ASF) under one or more
2+
contributor license agreements. See the NOTICE file distributed with
3+
this work for additional information regarding copyright ownership.
4+
The ASF licenses this file to You under the Apache License, Version 2.0
5+
(the "License"); you may not use this file except in compliance with
6+
the License. You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
16+
17+
@startuml
18+
19+
box client process
20+
participant Watcher
21+
control WatcherThread
22+
participant Fw
23+
participant mDNS_daemon
24+
end box
25+
Watcher->Fw:Register endpoint listener service tracker.\n(filter:"(!(DISCOVERY=true))")
26+
create WatcherThread
27+
Watcher ->WatcherThread:
28+
==setup==
29+
loop
30+
alt mDNS server disconnect
31+
WatcherThread->mDNS_daemon:DNSServiceCreateConnection
32+
return DNSServiceRef
33+
end alt
34+
alt browser is null
35+
WatcherThread->mDNS_daemon:DNSServiceBrowse(DNSServiceRef,anyInterface, "_celix-rpc._udp", "local"...)
36+
end alt
37+
mDNS_daemon-->WatcherThread:Service instances browsed
38+
alt Have new service instance \n or resolve service timeout
39+
WatcherThread->mDNS_daemon:DNSServiceResolve
40+
end
41+
mDNS_daemon-->WatcherThread:txt records
42+
WatcherThread->WatcherThread:Converting txt records to endpoint properties
43+
alt resolve completed
44+
WatcherThread->WatcherThread:Inform new endpoints to tpm (use endpoint listener service)
45+
end alt
46+
WatcherThread->WatcherThread:Remove expired endpoints(use endpoint listener service)
47+
note left
48+
If the service has been deleted for 10 seconds,
49+
we consider the endpoint to be expired.
50+
end note
51+
end loop
52+
53+
@enduml

0 commit comments

Comments
 (0)