linera_sdk/abis/
controller.rs

1// Copyright (c) Zefchain Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use std::collections::BTreeMap;
5
6use async_graphql::{scalar, Request, Response, SimpleObject};
7use linera_sdk_derive::GraphQLMutationRootInCrate;
8use serde::{Deserialize, Serialize};
9
10use crate::linera_base_types::{
11    AccountOwner, ApplicationId, ChainId, ContractAbi, DataBlobHash, MessagePolicy, ServiceAbi,
12};
13
14pub struct ControllerAbi;
15
16impl ContractAbi for ControllerAbi {
17    type Operation = Operation;
18    type Response = ();
19}
20
21impl ServiceAbi for ControllerAbi {
22    type Query = Request;
23    type QueryResponse = Response;
24}
25
26/// Service are identified by the blob ID of the description.
27pub type ManagedServiceId = DataBlobHash;
28
29#[derive(Debug, Deserialize, Serialize, GraphQLMutationRootInCrate)]
30pub enum Operation {
31    /// Worker commands
32    ExecuteWorkerCommand {
33        owner: AccountOwner,
34        command: WorkerCommand,
35    },
36    /// Execute a controller command
37    ExecuteControllerCommand {
38        admin: AccountOwner,
39        command: ControllerCommand,
40    },
41}
42
43/// A worker command
44#[derive(Clone, Debug, Deserialize, Serialize)]
45pub enum WorkerCommand {
46    /// Executed by workers to register themselves.
47    RegisterWorker { capabilities: Vec<String> },
48    /// Executed by workers to de-register themselves.
49    DeregisterWorker,
50}
51
52scalar!(WorkerCommand);
53
54/// A controller command
55#[derive(Clone, Debug, Deserialize, Serialize)]
56pub enum ControllerCommand {
57    /// Set the admin owners.
58    SetAdmins { admins: Option<Vec<AccountOwner>> },
59    /// Remove a worker. (This should not usually happen, but some workers may be broken
60    /// and need to be cleaned up.)
61    RemoveWorker { worker_id: ChainId },
62    /// Update the state of a particular service to be running on the specific workers.
63    UpdateService {
64        service_id: ManagedServiceId,
65        workers: Vec<ChainId>,
66    },
67    /// Remove a service from the map entirely.
68    RemoveService { service_id: ManagedServiceId },
69    /// Set the states of all services at once, possibly removing some of them.
70    UpdateAllServices {
71        services: Vec<(ManagedServiceId, Vec<ChainId>)>,
72    },
73    /// Update the state of a particular chain to be listened to on the specific workers.
74    UpdateChain {
75        chain_id: ChainId,
76        workers: Vec<ChainId>,
77    },
78    /// Remove a chain from the map entirely.
79    RemoveChain { chain_id: ChainId },
80    /// Set the states of all chains at once, possibly removing some of them.
81    UpdateAllChains {
82        chains: Vec<(ChainId, Vec<ChainId>)>,
83    },
84}
85
86scalar!(ControllerCommand);
87
88/// The description of a service worker.
89#[derive(Clone, Debug, Serialize, Deserialize, SimpleObject)]
90pub struct Worker {
91    /// The address used by the worker.
92    pub owner: AccountOwner,
93    /// Some tags denoting the capabilities of this worker. Each capability has a value
94    /// that the worker will read from its local environment and pass to the applications.
95    pub capabilities: Vec<String>,
96}
97
98/// The description of a service managed by the controller.
99#[derive(Clone, Debug, Serialize, Deserialize)]
100pub struct ManagedService {
101    /// The application ID running the service (e.g. pm-engine)
102    pub application_id: ApplicationId,
103    /// The role assumed by this service within the application (e.g. engine, event,
104    /// market-maker).
105    pub name: String,
106    /// The chain on which the service is run. Note that this is different from the worker
107    /// chains which typically only run the controller application for managing the worker
108    /// itself.
109    pub chain_id: ChainId,
110    /// The required capabilities for a worker to be useful (e.g. some API key).
111    /// Concretely, the worker will read its environment variable
112    pub requirements: Vec<String>,
113}
114
115scalar!(ManagedService);
116
117/// The local state of a worker.
118// This is used to facilitate service queries.
119#[derive(Clone, Debug, Deserialize, Serialize)]
120pub struct LocalWorkerState {
121    /// The description of this worker as we registered it.
122    pub local_worker: Option<Worker>,
123    /// The services currently running locally.
124    pub local_services: Vec<ManagedService>,
125    /// The chains currently followed locally (besides ours and the active service
126    /// chains).
127    pub local_chains: Vec<ChainId>,
128    /// The message policy that should be followed by the worker.
129    pub local_message_policy: BTreeMap<ChainId, MessagePolicy>,
130}
131
132scalar!(LocalWorkerState);
linera_sdk/abis/controller.rs

linera_sdk/abis/
controller.rs
