h1. Remote Service Introduction

Remote service in distributed systems are using two separate, independent steps, to get them work. These are *Service Discovery* and *Distribution*. 

Beside that there is a distinction between service *consumer* and *producer* (client/consumer and server/producer).


Service discovery is for publishing service descriptions to potential consumers about new, changed or removed services. 

Distribution is the handling of the remote calls itself, according to their service description. 


h2. Client

RemoteService Client/Consumer consumes remote services. That means it provides a service proxy in its own OSGi framework. Request against the consumed service are delegated to the corresponding remote system. For that the RemoteServiceAdmin implementation is used for this service.

To determine, what the correct implementation is, the service description is important. The client receives the service description over the discovery mechanism.

h3. Discovery

# publish a get all descriptions command
# receive the initial descriptions
# receive RemoteService add: topic
# receive RemoveService change: topic
# receive RemoteService remove: topic

h3. Distribution

* create service proxy with the corresponding endpoint-client delegation for new services descriptions
* change service proxies when a service description change occurs
* remove service proxies, when a removal of a service description occurs.
* create RPC request (serialize request)
* convert RPC reponses (de-serialize response)
* create Stream request (serialize request) and subscribe on a certain request-topic
* convert response stream, handle acknowledge, back-pressure

h2. Server

RemoteService Server/Producer publishes services to connected systems. It provides endpoints for services, that are marked as remote service. For them service description are created and each change of the service is then converted into a service description and published to the distributed system. 

The endpoints may be different implementations of protocols, that delegate and convert the remote request corresponding to the service signature and delegate the calls to the real service and convert and send the response over the endpoint.

h3. Discovery

# publish all existing remote service descriptions
# publish all new added service descriptions
# publish all modified service descriptions
# publish all removed service descriptions
# receive all get all description commands that are usually send by clients and
# publish all get all command responses

h3. Distribution

* create endpoints for new services
* change endpoints, if service changes
* removed endpoint, if service removed
* receive RPC requests (de-serialize request)
* handle request and submit RPC response (serialize response)
* receive Stream requests (de-serialize request)
* handle stream, with back-pressure and submit n-reponses over the topic (serialize each message)

h2. Overview 

h3. Discovery

| *Use-Case* | *Server* | *Client* | Message Pattern |
| initial start server | pub all descriptions | sub all descriptions | topic pub/sub send&forget |
| initial start client | sub get all command + sub all descriptions | pub get all command | topic RPC 1 x pub/ n x sub |  
| add service | pub description | sub description | topic pub/sub send&forget |
| modify service | pub description | sub description | topic pub/sub send&forget |
| remove service | pub description | sub description | topic pub/sub send&forget |

h3. Distribution

| *Use-Case* | *Client* | *Server* | Message Pattern |
| RPC call request | pub request | sub request + handleCall | queue/topic RPC |
| RPC call response | sub response | pub response | queue/topic RPC |
| Stream call request | pub open stream command | sub stream request + handleCall | queue/topic  pub/sub |
| Stream call response | sub response stream | pub stream messages | queue/topic  pub/sub |
| Stream command open | pub open command | sub command + pub stream messages | queue/topic  pub/sub command:send&forget |
| Stream command close/error | pub close/response command | sub command + handle close/error | queue/topic  pub/sub command:send&forget |