-
Notifications
You must be signed in to change notification settings - Fork 24
Philosophy of the Design
In general, the API for accessing connections and entities has a few high-level goals:
-
Hide the details of the underlying implementation, allowing a developer to focus only on the explicit contract defined (as is common of any API)
-
Maintain a small surface area, alleviating the need to redundantly implement a broader API directly within the implementation
-
Approach the API as a primitive layer, allowing the complexity to grow on top of it, rather than below it
This last point is highly important as it allows for the reuse of this richer library of functionality across different implementations. Specifically, this allows the passthrough implementation to be used to build/test the functional layer, instead of being a reason to duplicate this across both implementations of the API. This ability to turn a liability into an asset is very attractive. This is why changes which would push this complexity down into the implementation are resisted.
Beyond that, the overarching ideas behind the API are related to the assumption that functionality will be added to the platform as external modules (entities and services) registered within the implementation. This means that high-level functionality required by applications wishing to use the cluster should not be added to the API, but built as entity or service modules for the needs of that application.
In fact, this idea is taken further through the standard-cluster-services module. This is a collection of service interfaces defined by the platform API, directly, in order to allow for richer interactions, in cases where the API would otherwise need to be made far richer.
In some cases, such as ClientCommunicator, this is a service defining a behavior which entity modules typically require but can only be provided by an implementation (as it defines the nature of such communications). Exposing these pieces of functionality as services allows for a generalized way for entities to access them without creating more specialized APIs.
In other cases, such as IPlatformPersistence, this is a service which the implementation can use if it is provided by a plugged-in service. This allows the nature of such pieces of functionality to be considered opaque to the platform, where they would otherwise require a great deal of direct configuration and visibility.