The client-adapter-rust software package enables application developers and system integrators to create distributed IIoT solutions in compliance with the Arrowhead framework specification by delivering client-side implementation of the mandatory Arrowhead core services (version 4.4.0). client-adapter-rust is written in Rust and makes use of open source libraries available on crates.io. It is released both as a software library for application developers and as executable configuration tool for system integrators.
This software is develped upon a specification which is (roughly) the same as that of client-adapter-qt which is released under GNU LGPL license and is available here. The key differences are the following:
- client-adapter-rust only providers interface for mandatory core systems (Service Registry, Orchestrator and Authorization) while client-adapter-qt makes use of onboarding core systems (Onboarding Controller, Device Registry, System Registry) too.
- client-adapter-qt also contains pre-built Docker images for easier deployment
client-adapter-rust consists of two Cargo projects (ah_system_adapter and ah_adapter_app). You can use standard Cargo commands (cargo build, cargo run, cargo test) to build, execute or test the source code.
To learn more about the installation of Cargo, follow this link.
ah_system_adapter is a Cargo package containing a library crate with the same name. It also contains some related unit tests.
The reader is required to have a good understanding of the Arrowhead framework before using ah_system_adapter. Please consult the Arrowhead core repository for detailed documentation with special focus on the Service Registry, Authorization and Orchestrator core systems and their public client services.
- Implements Arrowhead client functionalities
- Client-side implementation of mandatory core services
- Supported Arrowhead version: 4.4.0
- Supported core interfaces
- Service Registry interface
- echo
- register
- unregister
- query
- Authorization interface
- echo
- get public key
- Orchestrator interface
- echo
- request orchestration
- start store orchestration by id
- Target users:
- software developers responsible for creating Arrowhead-compliant application systems and services
- Service Registry interface
This library currently only supports unsecured HTTP connection, so Arrowhead Systems must be configured that way.
The library must be initialized by instantiating a ArrowheadSystemAdapter struct using ArrowheadSystemAdapter::new() method.
The method requires the following parameters:
service_registry_address: &str- the base URL of the Service Registry core system,authorization_address: &str- the base URL of the Authorization core system,orchestrator_address: &str- the base URL of the Orchestrator core system,client_system: ArrowheadSystem<NoEntryTag>- the specification of the client system, which will be adapted to the Arrowhead local cloud.
The interface struct ArrowheadSystemAdapter has the following public functions:
- echo_service_registry
- query_service
- register_service
- unregister_service
- echo_authorization_system
- get_public_key
- echo_orchestrator
- request_orchestration
- request_orchestration_by_id
The library performs blocking network calls. Each interface function returns a Result<T, Error> enum (referenced as Result<T> from this on) where T (a template parameter) is the return type of the different functions. The error enum Error has the following variants:
| Variant | Meaning |
|---|---|
Error::HttpError(String) |
An HTTP-related error occured when trying to send request |
Error::ArrowheadError(ArrowheadServerException) |
The the request to the Arrowhead Service returned with an Arrowhead-specific client error |
fn echo_service_registry() -> Result<()>The echo_service_registry function tests connection to the Service Registry by using its Echo interface.
fn query_service(service_query_form: &ServiceQueryForm) -> Result<ServiceQueryList>The query_service function queries the Service Registry for the presence of the indicated service.
Direct lookups from Application Systems within the network is not advised in Arrowhead generation 4.4.0, due to security reasons.
fn register_service(register_service_input: RegisterServiceInput) - Result<ArrowheadService<EntryTag>>The register_service function registers an application service to the Service Registry.
fn unregister_service(service_definition: &str) -> Result<()>The unregister_service function deregisters from the Service Registry the application service defined by the service_definition input argument.
fn echo_authorization_system() -> Result<()>The echo_authorization_system function tests connection to the Authorization System by using its Echo interface.
fn get_public_key() -> Result<String>The get_public_key function returns the public key of the Authorization System as a base64 encoded string.
Only applicable with SSL enabled.
fn echo_orchestrator() -> Result<()>The echo_orchestrator function tests connection to the Orchestrator by using its Echo interface.
fn request_orchestration(request_orchestration_input: RequestOrchestrationInput) -> Result<OrchestrationResponse>The request_orchestration function requests service orchestration from the Orchestrator.
The default orchestration-method is store-based orchestration. Dynamic orchestration request shall be specified by setting the overrideStore orchestration flag in the RequestOrchestrationInput. See the Arrowhead core documentation for further details.
fn request_orchestration_by_id(id: i64) -> Result<OrchestrationResponse>The request_orchestration_by_id function requests service orchestration from the Orchestrator using the store entry id of the requester system.
The data structs implemented by the library are specified by the requested Arrowhead core services. The definition of the input forms and output responses can be found in the Arrowhead core documentation. The Class Diagram of the library is presented in Figure 1:
Figure 1 - ah_system_adapter Data Types Class Diagram
ah_adapter_app is a Cargo package containing a binary crate with the same name.
It provides an easy-to-use command line interface for:
- service registration/deregistration
- public key request for the system
- orchestration request
Please follow this link for the User manual.
Please follow this link for the Developer manual.