referrerpolicy=no-referrer-when-downgrade

sc_offchain/
api.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
5
6// This program is free software: you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation, either version 3 of the License, or
9// (at your option) any later version.
10
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// You should have received a copy of the GNU General Public License
17// along with this program. If not, see <https://www.gnu.org/licenses/>.
18
19use std::{collections::HashSet, str::FromStr, sync::Arc, thread::sleep};
20
21use crate::NetworkProvider;
22use codec::{Decode, Encode};
23use futures::Future;
24pub use http::SharedClient;
25use sc_network::Multiaddr;
26use sc_network_types::PeerId;
27use sp_core::{
28	offchain::{
29		self, HttpError, HttpRequestId, HttpRequestStatus, OpaqueMultiaddr, OpaqueNetworkState,
30		Timestamp,
31	},
32	OpaquePeerId,
33};
34
35mod http;
36
37mod timestamp;
38
39/// Asynchronous offchain API.
40///
41/// NOTE this is done to prevent recursive calls into the runtime
42/// (which are not supported currently).
43pub(crate) struct Api {
44	/// A provider for substrate networking.
45	network_provider: Arc<dyn NetworkProvider + Send + Sync>,
46	/// Is this node a potential validator?
47	is_validator: bool,
48	/// Everything HTTP-related is handled by a different struct.
49	http: http::HttpApi,
50}
51
52impl offchain::Externalities for Api {
53	fn is_validator(&self) -> bool {
54		self.is_validator
55	}
56
57	fn network_state(&self) -> Result<OpaqueNetworkState, ()> {
58		let external_addresses = self.network_provider.external_addresses();
59
60		let state = NetworkState::new(self.network_provider.local_peer_id(), external_addresses);
61		Ok(OpaqueNetworkState::from(state))
62	}
63
64	fn timestamp(&mut self) -> Timestamp {
65		timestamp::now()
66	}
67
68	fn sleep_until(&mut self, deadline: Timestamp) {
69		sleep(timestamp::timestamp_from_now(deadline));
70	}
71
72	fn random_seed(&mut self) -> [u8; 32] {
73		rand::random()
74	}
75
76	fn http_request_start(
77		&mut self,
78		method: &str,
79		uri: &str,
80		_meta: &[u8],
81	) -> Result<HttpRequestId, ()> {
82		self.http.request_start(method, uri)
83	}
84
85	fn http_request_add_header(
86		&mut self,
87		request_id: HttpRequestId,
88		name: &str,
89		value: &str,
90	) -> Result<(), ()> {
91		self.http.request_add_header(request_id, name, value)
92	}
93
94	fn http_request_write_body(
95		&mut self,
96		request_id: HttpRequestId,
97		chunk: &[u8],
98		deadline: Option<Timestamp>,
99	) -> Result<(), HttpError> {
100		self.http.request_write_body(request_id, chunk, deadline)
101	}
102
103	fn http_response_wait(
104		&mut self,
105		ids: &[HttpRequestId],
106		deadline: Option<Timestamp>,
107	) -> Vec<HttpRequestStatus> {
108		self.http.response_wait(ids, deadline)
109	}
110
111	fn http_response_headers(&mut self, request_id: HttpRequestId) -> Vec<(Vec<u8>, Vec<u8>)> {
112		self.http.response_headers(request_id)
113	}
114
115	fn http_response_read_body(
116		&mut self,
117		request_id: HttpRequestId,
118		buffer: &mut [u8],
119		deadline: Option<Timestamp>,
120	) -> Result<usize, HttpError> {
121		self.http.response_read_body(request_id, buffer, deadline)
122	}
123
124	fn set_authorized_nodes(&mut self, nodes: Vec<OpaquePeerId>, authorized_only: bool) {
125		let peer_ids: HashSet<PeerId> =
126			nodes.into_iter().filter_map(|node| PeerId::from_bytes(&node.0).ok()).collect();
127
128		self.network_provider.set_authorized_peers(peer_ids);
129		self.network_provider.set_authorized_only(authorized_only);
130	}
131}
132
133/// Information about the local node's network state.
134#[derive(Clone, Eq, PartialEq, Debug)]
135pub struct NetworkState {
136	peer_id: PeerId,
137	external_addresses: Vec<Multiaddr>,
138}
139
140impl NetworkState {
141	fn new(peer_id: PeerId, external_addresses: Vec<Multiaddr>) -> Self {
142		NetworkState { peer_id, external_addresses }
143	}
144}
145
146impl From<NetworkState> for OpaqueNetworkState {
147	fn from(state: NetworkState) -> OpaqueNetworkState {
148		let enc = Encode::encode(&state.peer_id.to_bytes());
149		let peer_id = OpaquePeerId::new(enc);
150
151		let external_addresses: Vec<OpaqueMultiaddr> = state
152			.external_addresses
153			.iter()
154			.map(|multiaddr| {
155				let e = Encode::encode(&multiaddr.to_string());
156				OpaqueMultiaddr::new(e)
157			})
158			.collect();
159
160		OpaqueNetworkState { peer_id, external_addresses }
161	}
162}
163
164impl TryFrom<OpaqueNetworkState> for NetworkState {
165	type Error = ();
166
167	fn try_from(state: OpaqueNetworkState) -> Result<Self, Self::Error> {
168		let inner_vec = state.peer_id.0;
169
170		let bytes: Vec<u8> = Decode::decode(&mut &inner_vec[..]).map_err(|_| ())?;
171		let peer_id = PeerId::from_bytes(&bytes).map_err(|_| ())?;
172
173		let external_addresses: Result<Vec<Multiaddr>, Self::Error> = state
174			.external_addresses
175			.iter()
176			.map(|enc_multiaddr| -> Result<Multiaddr, Self::Error> {
177				let inner_vec = &enc_multiaddr.0;
178				let bytes = <Vec<u8>>::decode(&mut &inner_vec[..]).map_err(|_| ())?;
179				let multiaddr_str = String::from_utf8(bytes).map_err(|_| ())?;
180				let multiaddr = Multiaddr::from_str(&multiaddr_str).map_err(|_| ())?;
181				Ok(multiaddr)
182			})
183			.collect();
184		let external_addresses = external_addresses?;
185
186		Ok(NetworkState { peer_id, external_addresses })
187	}
188}
189
190/// Offchain extensions implementation API
191///
192/// This is the asynchronous processing part of the API.
193pub(crate) struct AsyncApi {
194	/// Everything HTTP-related is handled by a different struct.
195	http: Option<http::HttpWorker>,
196}
197
198impl AsyncApi {
199	/// Creates new Offchain extensions API implementation and the asynchronous processing part.
200	pub fn new(
201		network_provider: Arc<dyn NetworkProvider + Send + Sync>,
202		is_validator: bool,
203		shared_http_client: SharedClient,
204	) -> (Api, Self) {
205		let (http_api, http_worker) = http::http(shared_http_client);
206
207		let api = Api { network_provider, is_validator, http: http_api };
208
209		let async_api = Self { http: Some(http_worker) };
210
211		(api, async_api)
212	}
213
214	/// Run a processing task for the API
215	pub fn process(self) -> impl Future<Output = ()> {
216		self.http.expect("`process` is only called once; qed")
217	}
218}
219
220#[cfg(test)]
221mod tests {
222	use super::*;
223	use sc_client_db::offchain::LocalStorage;
224	use sc_network::{
225		config::MultiaddrWithPeerId, types::ProtocolName, NetworkPeers, NetworkStateInfo,
226		ObservedRole, ReputationChange,
227	};
228	use sp_core::offchain::{storage::OffchainDb, DbExternalities, Externalities, StorageKind};
229	use std::time::SystemTime;
230
231	pub(super) struct TestNetwork();
232
233	#[async_trait::async_trait]
234	impl NetworkPeers for TestNetwork {
235		fn set_authorized_peers(&self, _peers: HashSet<PeerId>) {
236			unimplemented!();
237		}
238
239		fn set_authorized_only(&self, _reserved_only: bool) {
240			unimplemented!();
241		}
242
243		fn add_known_address(&self, _peer_id: PeerId, _addr: Multiaddr) {
244			unimplemented!();
245		}
246
247		fn report_peer(&self, _peer_id: PeerId, _cost_benefit: ReputationChange) {
248			unimplemented!();
249		}
250
251		fn peer_reputation(&self, _peer_id: &PeerId) -> i32 {
252			unimplemented!()
253		}
254
255		fn disconnect_peer(&self, _peer_id: PeerId, _protocol: ProtocolName) {
256			unimplemented!();
257		}
258
259		fn accept_unreserved_peers(&self) {
260			unimplemented!();
261		}
262
263		fn deny_unreserved_peers(&self) {
264			unimplemented!();
265		}
266
267		fn add_reserved_peer(&self, _peer: MultiaddrWithPeerId) -> Result<(), String> {
268			unimplemented!();
269		}
270
271		fn remove_reserved_peer(&self, _peer_id: PeerId) {
272			unimplemented!();
273		}
274
275		fn set_reserved_peers(
276			&self,
277			_protocol: ProtocolName,
278			_peers: HashSet<Multiaddr>,
279		) -> Result<(), String> {
280			unimplemented!();
281		}
282
283		fn add_peers_to_reserved_set(
284			&self,
285			_protocol: ProtocolName,
286			_peers: HashSet<Multiaddr>,
287		) -> Result<(), String> {
288			unimplemented!();
289		}
290
291		fn remove_peers_from_reserved_set(
292			&self,
293			_protocol: ProtocolName,
294			_peers: Vec<PeerId>,
295		) -> Result<(), String> {
296			unimplemented!();
297		}
298
299		fn sync_num_connected(&self) -> usize {
300			unimplemented!();
301		}
302
303		fn peer_role(&self, _peer_id: PeerId, _handshake: Vec<u8>) -> Option<ObservedRole> {
304			None
305		}
306
307		async fn reserved_peers(&self) -> Result<Vec<PeerId>, ()> {
308			unimplemented!();
309		}
310	}
311
312	impl NetworkStateInfo for TestNetwork {
313		fn external_addresses(&self) -> Vec<Multiaddr> {
314			Vec::new()
315		}
316
317		fn local_peer_id(&self) -> PeerId {
318			PeerId::random()
319		}
320
321		fn listen_addresses(&self) -> Vec<Multiaddr> {
322			Vec::new()
323		}
324	}
325
326	fn offchain_api() -> (Api, AsyncApi) {
327		sp_tracing::try_init_simple();
328		let mock = Arc::new(TestNetwork());
329		let shared_client = SharedClient::new().unwrap();
330
331		AsyncApi::new(mock, false, shared_client)
332	}
333
334	fn offchain_db() -> OffchainDb<LocalStorage> {
335		OffchainDb::new(LocalStorage::new_test())
336	}
337
338	#[test]
339	fn should_get_timestamp() {
340		let mut api = offchain_api().0;
341
342		// Get timestamp from std.
343		let now = SystemTime::now();
344		let d: u64 = now
345			.duration_since(SystemTime::UNIX_EPOCH)
346			.unwrap()
347			.as_millis()
348			.try_into()
349			.unwrap();
350
351		// Get timestamp from offchain api.
352		let timestamp = api.timestamp();
353
354		// Compare.
355		assert!(timestamp.unix_millis() > 0);
356		assert!(timestamp.unix_millis() >= d);
357	}
358
359	#[test]
360	fn should_sleep() {
361		let mut api = offchain_api().0;
362
363		// Arrange.
364		let now = api.timestamp();
365		let delta = sp_core::offchain::Duration::from_millis(100);
366		let deadline = now.add(delta);
367
368		// Act.
369		api.sleep_until(deadline);
370		let new_now = api.timestamp();
371
372		// Assert.
373		// The diff could be more than the sleep duration.
374		assert!(new_now.unix_millis() - 100 >= now.unix_millis());
375	}
376
377	#[test]
378	fn should_set_get_and_clear_local_storage() {
379		// given
380		let kind = StorageKind::PERSISTENT;
381		let mut api = offchain_db();
382		let key = b"test";
383
384		// when
385		assert_eq!(api.local_storage_get(kind, key), None);
386		api.local_storage_set(kind, key, b"value");
387
388		// then
389		assert_eq!(api.local_storage_get(kind, key), Some(b"value".to_vec()));
390
391		// when
392		api.local_storage_clear(kind, key);
393
394		// then
395		assert_eq!(api.local_storage_get(kind, key), None);
396	}
397
398	#[test]
399	fn should_compare_and_set_local_storage() {
400		// given
401		let kind = StorageKind::PERSISTENT;
402		let mut api = offchain_db();
403		let key = b"test";
404		api.local_storage_set(kind, key, b"value");
405
406		// when
407		assert_eq!(api.local_storage_compare_and_set(kind, key, Some(b"val"), b"xxx"), false);
408		assert_eq!(api.local_storage_get(kind, key), Some(b"value".to_vec()));
409
410		// when
411		assert_eq!(api.local_storage_compare_and_set(kind, key, Some(b"value"), b"xxx"), true);
412		assert_eq!(api.local_storage_get(kind, key), Some(b"xxx".to_vec()));
413	}
414
415	#[test]
416	fn should_compare_and_set_local_storage_with_none() {
417		// given
418		let kind = StorageKind::PERSISTENT;
419		let mut api = offchain_db();
420		let key = b"test";
421
422		// when
423		let res = api.local_storage_compare_and_set(kind, key, None, b"value");
424
425		// then
426		assert_eq!(res, true);
427		assert_eq!(api.local_storage_get(kind, key), Some(b"value".to_vec()));
428	}
429
430	#[test]
431	fn should_convert_network_states() {
432		// given
433		let state = NetworkState::new(
434			PeerId::random(),
435			vec![
436				Multiaddr::try_from("/ip4/127.0.0.1/tcp/1234".to_string()).unwrap(),
437				Multiaddr::try_from("/ip6/2601:9:4f81:9700:803e:ca65:66e8:c21").unwrap(),
438			],
439		);
440
441		// when
442		let opaque_state = OpaqueNetworkState::from(state.clone());
443		let converted_back_state = NetworkState::try_from(opaque_state).unwrap();
444
445		// then
446		assert_eq!(state, converted_back_state);
447	}
448
449	#[test]
450	fn should_get_random_seed() {
451		// given
452		let mut api = offchain_api().0;
453		let seed = api.random_seed();
454		// then
455		assert_ne!(seed, [0; 32]);
456	}
457}