Improve doc

[xuzhenbao]

Improve document for RSA and DFI

It fixes #510.

[PengZheng]

LGTM.

Nice work! I learned a lot from reviewing it. The dfi documentation is especially valuable.
There are ambiguities which need clarification, though.
And by reading it, I found a serious design flaw of discovery_zeroconf that needs to be addressed by another PR, which illustrates from another aspect the usefulness of this PR.

[PengZheng]

The content of TXT is set by the service provider. This design will force them to watch for address change, which violates the rationale of zeroconf and suggests a severe design flaw. I'll have a good read of RFC 6762 and 6763 this weekend before making further comments on this.

[PengZheng]

This does not feel right. Currently, service descriptor is bundled by its various consumers.
THis is far less than ideal. We'd better let service discovery and RSA fetch service descriptors from service providers at runtime. Alternatively, we can generate the descriptor from the service header, i.e. solve #590.

In the same process, there should be one unique copy of service descriptor for each remote service instance.

[pnoltes]

In the same process, there should be one unique copy of service descriptor for each remote service instance.

I think this is the key issue. Only 1 unique descriptor for a service per process.

Ideally the consumer and provider are also aligned, but this is not always necessary. It is possible for the provider to provide newer version of the service, as long as it is backwards compatible.

For example a consumer using the following service:

#define FOO_SERVICE_NAME "foo"
#define FOO_SERVICE_VERSION "1.0.0"

struct {
  void* handle;
  int foo(const char* string); 
} my_service

Can use a remote! provided service with the following service:

#define FOO_SERVICE_NAME "foo"
#define FOO_SERVICE_VERSION "1.1.0"

struct {
  void* handle;
  int bar(const char* string);
  int foo(const char* string); 
} my_service

Note that because bar is added before foo the updated service is not binary backwards compatible inside the same process. But for remote calls, as long as we can identity which method signature is called, different service versions is possible.

For the pubsub serializer handler different version is actual handled:
https://github.com/apache/celix/blob/rel/celix-2.4.0/bundles/pubsub/pubsub_utils/src/pubsub_serializer_handler.c#L237-L242

I also though there was a check on the literal descriptor content, but apparently not.

[PengZheng]

Now that we have *, why we need t for char *?

[pnoltes]

I think the t is not really necessary anymore. IIRC I added the t for 2 reasons:

1. Although C uses a char* as string, in other languages a string type is often a special built-in type.
2. In the beginning of libdfi there was not support to specific if something was a pointer or not, so t was needed to specify a char*, now *B can be used.

[PengZheng]

Maybe we still need char * for plain char * and t for null-terminate c string.

[PengZheng]

Now that we have *, why we need *l?

[pnoltes]

Given the support for *, I think we can drop L and t so that we do not have alternatives so "say" the same thing.

[pnoltes]

It's great to see some sorely missed documentation being added. I will try to review this PR this week.

[pnoltes]

Nice work :). I do have some remarks, but overall this looks good.

[pnoltes]

Why is the service name still used, a UUID should be unique enough. Is this for readability/debugging?

[PengZheng]

Usage of UUID in instance name is explicitly discourage by RFC 6763:

The default name should be short and
descriptive, and SHOULD NOT include the device's Media Access Control
(MAC) address, serial number, or any similar incomprehensible
hexadecimal string in an attempt to make the name globally unique.

The rational is explained here.

Therefore, UUID should be removed from instance name altogether.

[pnoltes]

Nice to see the usage of plant UML for some diagrams 😄

[pnoltes]

Again nice to see some sequence diagrams. Especially for a complex sequence like a remote call over the remote service admin 👍

[pnoltes]

In the same process, there should be one unique copy of service descriptor for each remote service instance.

I think this is the key issue. Only 1 unique descriptor for a service per process.

Ideally the consumer and provider are also aligned, but this is not always necessary. It is possible for the provider to provide newer version of the service, as long as it is backwards compatible.

For example a consumer using the following service:

#define FOO_SERVICE_NAME "foo"
#define FOO_SERVICE_VERSION "1.0.0"

struct {
  void* handle;
  int foo(const char* string); 
} my_service

Can use a remote! provided service with the following service:

#define FOO_SERVICE_NAME "foo"
#define FOO_SERVICE_VERSION "1.1.0"

struct {
  void* handle;
  int bar(const char* string);
  int foo(const char* string); 
} my_service

Note that because bar is added before foo the updated service is not binary backwards compatible inside the same process. But for remote calls, as long as we can identity which method signature is called, different service versions is possible.

For the pubsub serializer handler different version is actual handled:
https://github.com/apache/celix/blob/rel/celix-2.4.0/bundles/pubsub/pubsub_utils/src/pubsub_serializer_handler.c#L237-L242

I also though there was a check on the literal descriptor content, but apparently not.

[pnoltes]

I think the t is not really necessary anymore. IIRC I added the t for 2 reasons:

1. Although C uses a char* as string, in other languages a string type is often a special built-in type.
2. In the beginning of libdfi there was not support to specific if something was a pointer or not, so t was needed to specify a char*, now *B can be used.

[pnoltes]

Given the support for *, I think we can drop L and t so that we do not have alternatives so "say" the same thing.

[PengZheng]

I've finished reading RFC 6762 and 6763 (word by word), and have some further remarks on discovery_zeroconf:

Large TXT Records

As previously pointed out by @pnoltes in an email:

One of the issue we had with mDNS, is that payload size is very
limited and as result the remote service discovery was updated to a 2
step approach:

The current design adopt the approach sketched by Service Instances with Multiple TXT Records
.
For this to work reliably, care must be taken to make sure that IP fragmentation does not happen, because

Even on hosts that normally
handle Ethernet "Jumbo" packets and IP fragment reassembly, it is
becoming more common for these hosts to implement power-saving modes
where the main CPU goes to sleep and hands off packet reception tasks
to a more limited processor in the network interface hardware, which
may not support Ethernet "Jumbo" packets or IP fragment reassembly.

A snapshot of mDNS wireshark capture will be very helpful to illustrate the current approach.

From the current documentation (I have not checked the implementation), it is not clear how we deal with packet loss.
For service whose service advertisement fit in a single message, it is never a problem. But for services generating large TXT records, how do we guarantee to collect all associated TXT records.

Do we have a test case for packet loss? I fully understand it is challenging to test this. But if we do have one, it rocks.

Fixed Hostname and Port in SRV

As mentioned above, this basically defeats the purpose of zeroconf. Don't do this!
Let just use the hostname of the OS.
For RSA over HTTP, port should be the real port listened by the HTTP server.
For RSA over shared memory, port could be 0.

It is OK to store URL in TXT records, but note that

The target host name and TCP (or UDP) port number of the service are
given in the SRV record. This information -- target host name and
port number -- MUST NOT be duplicated using key/value attributes in
the TXT record.

URL/URI does not necessarily contain host and port. For more, check URI Syntax Components.

Service Instance Name and Service Subtypes

If the application uses rsa_shm alone, then only service instances exported by rsa_shm should be discovered.
This is not the case (and less than ideal) for the current implementation: all service instances are enumerated by discovery_zeroconf. By using service subtypes, if the application only uses rsa_shm, discovery_zeroconf should search for something like _shm._sub._celix-rpc._udp rather than _celix-rpc._udp. For a user who want to list all exported services for debugging purpose, he/she can search for _celix-rpc._udp. Check Selective Instance Enumeration for more on service subtypes.

We only relies on the uniqueness of service instance name, otherwise It's mostly used for debugging.
Fortunately, we only need to provide an informative name, mDNSResponder will help to guarantee its uniqueness:

The default name should be short and
descriptive, and SHOULD NOT include the device's Media Access Control
(MAC) address, serial number, or any similar incomprehensible
hexadecimal string in an attempt to make the name globally unique.
For discussion of why names don't need to be (and SHOULD
NOT be) made unique at the factory, see Appendix D, "Choice of
Factory-Default Names".

Service name alone is not informative enough. I suggest we include pid of the service provider, which is very important for debugging a misbehaved remote service.

A shell command or the existing mDNSResponder command tool should be a useful debugging tool.

[PengZheng]

Given that #710 has been merged, is this PR ready now? @xuzhenbao @pnoltes
Note that parts of #699 may need to be updated into this.

[xuzhenbao]

Given that #710 has been merged, is this PR ready now? @xuzhenbao @pnoltes Note that parts of #699 may need to be updated into this.

I will update this PR, please wait a few day.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.45%. Comparing base (423abb8) to head (7b3ea01).
Report is 13 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #690      +/-   ##
==========================================
+ Coverage   89.32%   89.45%   +0.13%     
==========================================
  Files         216      216              
  Lines       25153    25294     +141     
==========================================
+ Hits        22468    22627     +159     
+ Misses       2685     2667      -18     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[xuzhenbao]

Hi @pnoltes
I have update this PR, it includes the following changes:

1. Add document for dynamic IP mechanism.
2. Add document for PR Feature/dfi cleanup #699 in libdfi README.md

[pnoltes]

Hi @pnoltes I have update this PR, it includes the following changes:

1. Add document for dynamic IP mechanism.

2. Add document for PR [Feature/dfi cleanup #699](https://github.com/apache/celix/pull/699) in libdfi README.md

Thanks, LGTM.