Summary

This page documents the ongoing design for the interaction of Jolie's MetaService and Plasma::Services. The interaction is bidirectional, allowing for two basic actions: service access and service exposure. Moreover, MetaService supports the loading of services that are written in Jolie instead of Plasma::Services.

Understanding JOLIE messages

Communications between MetaService and Plasma::Service follow the SODEP protocol specifications. The SODEP protocol message format is designed specifically for service-oriented communications and treats the basic concepts of JOLIE messaging (resources and operations) as first-class citizens.

While it is not important to know the SODEP message encoding specifications, it is relevant to know what its basic concepts are in order to understand this document and the MetaService API documentation.

A SODEP message comprises three parts:

Resource (string)
Operation (string)
Data (SODEP Value)

So we can represent a SODEP message as a triple: (Resource,Operation,Data). E.g., if we wanted to send a request for the "getNameById" operation of a service published under "/Registry", passing the value 5, we would use the following message: ("/Registry","getNameById",5).

Resource

Jolie resources are used to allow different services to share a single communication endpoint.

Suppose that you've published a Jolie service under the TCP port 8000. Now you want to publish other services under that port, so you need a means to disambiguate incoming messages on port 8000 because some messages will be for a service and some others for another service. Resources solve this problem.

A Jolie service can publish other services under its same communication endpoint by assigning them a resource name.

Say that we have three participants: A, R and B. R and B share the same communication endpoint for receiving input messages: R controls it and makes B accessible under resource "/Blah". Now A wants to send B a message, so it sends to R a message with resource name "/Blah". R will redirect the message to B and will take care of redirecting B's answer to A if necessary.

Operation

Operations are the basic block for a service interface. They stand to services as methods stand to objects.

Data

For the sake of this document it's not necessary to know the SODEP data representation. It suffices to say that SODEP supports complex data structures (vectors, trees, etc.).

Service access

Service access allows Plasma to access an external service. The external service can be wrapped inside a Plasma::Service in order to offer plasmoids the same API they use for internal Plasma::Services.

Service access is composed by two main steps:

Plasma asks MetaService to publish the external service under a specified resource name, specifying the protocol and transport mechanism used by the external service.
MetaService publishes the external service under the MetaService communication endpoint and returns to Plasma the resource name to use in order to reach it.

Now Plasma can send SODEP message to the resource pointed out by MetaService and these messages will be automatically redirected (and appropriately converted to the right protocol and transport mechanism) to the external service.

Service exposure

Service exposure allows Plasma to expose an internal Plasma::Service to external networks via MetaService.

Triggering Service Exposure

How will the user trigger exposing a service?
Migrating plasmoids between instances of Plasma

Workflow

When service exposure is triggered, Plasma::Service will:

Open a local listening socket using KLocalSocketServer
Generate a random token
Check if the Jolie MetaService is running and start it if it isn't
Contact MetaService and send the token, the redirect definition and the socket path to the "addRedirection" operation
Wait for a given period of time for MetaService to connect to the socket for confirmation, expecting a message for the "confirmRedirection" operation containing the token; if the token is right, then the Plasma::Service will answer with a message containing the integer 1, otherwise it will send an InvalidToken SODEP fault
Once connected it will forward operation requests received using SODEP to createJob and then execute the job internally, forwarding the response back to the MetaService for routing back to the client

Plasma::DataEngine

A Plasma::Service generic to the DataEngine API to expose any engine to MetaService?