stack_epic_api/
owner.rs

1// Copyright 2020 The Grin Developers
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Owner API External Definition
16
17use crate::chain::{Chain, SyncState};
18use crate::handlers::chain_api::{ChainCompactHandler, ChainValidationHandler};
19use crate::handlers::peers_api::{PeerHandler, PeersConnectedHandler};
20use crate::handlers::server_api::StatusHandler;
21use crate::p2p::types::PeerInfoDisplay;
22use crate::p2p::{self, PeerData};
23use crate::rest::*;
24use crate::types::Status;
25use std::net::SocketAddr;
26use std::sync::Weak;
27
28/// Main interface into all node API functions.
29/// Node APIs are split into two seperate blocks of functionality
30/// called the ['Owner'](struct.Owner.html) and ['Foreign'](struct.Foreign.html) APIs
31///
32/// Methods in this API are intended to be 'single use'.
33///
34
35pub struct Owner {
36	pub chain: Weak<Chain>,
37	pub peers: Weak<p2p::Peers>,
38	pub sync_state: Weak<SyncState>,
39}
40
41impl Owner {
42	/// Create a new API instance with the chain, transaction pool, peers and `sync_state`. All subsequent
43	/// API calls will operate on this instance of node API.
44	///
45	/// # Arguments
46	/// * `chain` - A non-owning reference of the chain.
47	/// * `tx_pool` - A non-owning reference of the transaction pool.
48	/// * `peers` - A non-owning reference of the peers.
49	/// * `sync_state` - A non-owning reference of the `sync_state`.
50	///
51	/// # Returns
52	/// * An instance of the Node holding references to the current chain, transaction pool, peers and sync_state.
53	///
54
55	pub fn new(chain: Weak<Chain>, peers: Weak<p2p::Peers>, sync_state: Weak<SyncState>) -> Self {
56		Owner {
57			chain,
58			peers,
59			sync_state,
60		}
61	}
62
63	/// Returns various information about the node, the network and the current sync status.
64	///
65	/// # Returns
66	/// * Result Containing:
67	/// * A [`Status`](types/struct.Status.html)
68	/// * or [`Error`](struct.Error.html) if an error is encountered.
69	///
70
71	pub fn get_status(&self) -> Result<Status, Error> {
72		let status_handler = StatusHandler {
73			chain: self.chain.clone(),
74			peers: self.peers.clone(),
75			sync_state: self.sync_state.clone(),
76		};
77		status_handler.get_status()
78	}
79
80	/// Trigger a validation of the chain state.
81	///
82	/// # Returns
83	/// * Result Containing:
84	/// * `Ok(())` if the validation was done successfully
85	/// * or [`Error`](struct.Error.html) if an error is encountered.
86	///
87
88	pub fn validate_chain(&self) -> Result<(), Error> {
89		let chain_validation_handler = ChainValidationHandler {
90			chain: self.chain.clone(),
91		};
92		chain_validation_handler.validate_chain()
93	}
94
95	/// Trigger a compaction of the chain state to regain storage space.
96	///
97	/// # Returns
98	/// * Result Containing:
99	/// * `Ok(())` if the compaction was done successfully
100	/// * or [`Error`](struct.Error.html) if an error is encountered.
101	///
102
103	pub fn compact_chain(&self) -> Result<(), Error> {
104		let chain_compact_handler = ChainCompactHandler {
105			chain: self.chain.clone(),
106		};
107		chain_compact_handler.compact_chain()
108	}
109
110	/// Retrieves information about stored peers.
111	/// If `None` is provided, will list all stored peers.
112	///
113	/// # Arguments
114	/// * `addr` - the ip:port of the peer to get.
115	///
116	/// # Returns
117	/// * Result Containing:
118	/// * A vector of [`PeerData`](types/struct.PeerData.html)
119	/// * or [`Error`](struct.Error.html) if an error is encountered.
120	///
121
122	pub fn get_peers(&self, addr: Option<SocketAddr>) -> Result<Vec<PeerData>, Error> {
123		let peer_handler = PeerHandler {
124			peers: self.peers.clone(),
125		};
126		peer_handler.get_peers(addr)
127	}
128
129	/// Retrieves a list of all connected peers.
130	///
131	/// # Returns
132	/// * Result Containing:
133	/// * A vector of [`PeerInfoDisplay`](types/struct.PeerInfoDisplay.html)
134	/// * or [`Error`](struct.Error.html) if an error is encountered.
135	///
136
137	pub fn get_connected_peers(&self) -> Result<Vec<PeerInfoDisplay>, Error> {
138		let peers_connected_handler = PeersConnectedHandler {
139			peers: self.peers.clone(),
140		};
141		peers_connected_handler.get_connected_peers()
142	}
143
144	/// Bans a specific peer.
145	///
146	/// # Arguments
147	/// * `addr` - the ip:port of the peer to ban.
148	///
149	/// # Returns
150	/// * Result Containing:
151	/// * `Ok(())` if the path was correctly set
152	/// * or [`Error`](struct.Error.html) if an error is encountered.
153	///
154
155	pub fn ban_peer(&self, addr: SocketAddr) -> Result<(), Error> {
156		let peer_handler = PeerHandler {
157			peers: self.peers.clone(),
158		};
159		peer_handler.ban_peer(addr)
160	}
161
162	/// Unbans a specific peer.
163	///
164	/// # Arguments
165	/// * `addr` -  the ip:port of the peer to unban.
166	///
167	/// # Returns
168	/// * Result Containing:
169	/// * `Ok(())` if the unban was done successfully
170	/// * or [`Error`](struct.Error.html) if an error is encountered.
171	///
172
173	pub fn unban_peer(&self, addr: SocketAddr) -> Result<(), Error> {
174		let peer_handler = PeerHandler {
175			peers: self.peers.clone(),
176		};
177		peer_handler.unban_peer(addr)
178	}
179}
stack_epic_api/owner.rs

stack_epic_api/
owner.rs
