Offchain-worker APIs stubs (#2615)

* WiP: HTTP Apis.

* Working on the API.

* Add docs, clean up the API.

* Expose ext_ stuff as well.

* Implement HTTP helpers for offchain sr-io.

* Remove HTTP stuff.

* Revert "Remove HTTP stuff."

This reverts commit 7cca029d6ae93c5849b50edfcc6d2c313ba3e5bf.

* HTTP apis.

* Additional offchain methods.

* Make it compile.

* Implement wasm-ext boundary of offchain methods.

* Add stubs for offchain stuff to prevent panics.

* Fix tests.

* Addres some more issues.

* Introduce typedef, use unsafe from_utf8

* Bump runtime version.

* Introduce error to distinguish deadline and io errors.

* Add local_storage_cas

* Some tests for offchain stuff.

* Address more grumbles.

* Fix tests compilation.

* Fix borked merge.

* Improve docs for expected return values from ext functions.

* Adding new sign/enrypt/decrypt APIs.

substrate/core/sr-io/src/lib.rs

@@ -33,6 +33,7 @@ use rstd::vec::Vec;
 pub use codec;
 
 pub use primitives::Blake2Hasher;
+use primitives::offchain::{Timestamp, HttpRequestId, HttpRequestStatus, HttpError, CryptoKind, CryptoKeyId};
 
 /// Error verifying ECDSA signature
 pub enum EcdsaVerifyError {
@@ -44,6 +45,8 @@ pub enum EcdsaVerifyError {
 	BadSignature,
 }
 
+pub mod offchain;
+
 /// Trait for things which can be printed.
 pub trait Printable {
 	/// Print the object.
@@ -226,12 +229,140 @@ export_api! {
 
 export_api! {
 	pub(crate) trait OffchainApi {
-		/// Submit extrinsic from the runtime.
+		/// Submit transaction to the pool.
 		///
-		/// Depending on the kind of extrinsic it will either be:
-		/// 1. scheduled to be included in the next produced block (inherent)
-		/// 2. added to the pool and propagated (transaction)
-		fn submit_extrinsic<T: codec::Encode>(data: &T);
+		/// The transaction will end up in the pool.
+		fn submit_transaction<T: codec::Encode>(data: &T) -> Result<(), ()>;
+
+		/// Create new key(pair) for signing/encryption/decryption.
+		///
+		/// Returns an error if given crypto kind is not supported.
+		fn new_crypto_key(crypto: CryptoKind) -> Result<CryptoKeyId, ()>;
+
+		/// Encrypt a piece of data using given crypto key.
+		///
+		/// If `key` is `None`, it will attempt to use current authority key.
+		///
+		/// Returns an error if `key` is not available or does not exist.
+		fn encrypt(key: Option<CryptoKeyId>, data: &[u8]) -> Result<Vec<u8>, ()>;
+
+		/// Decrypt a piece of data using given crypto key.
+		///
+		/// If `key` is `None`, it will attempt to use current authority key.
+		///
+		/// Returns an error if data cannot be decrypted or the `key` is not available or does not exist.
+		fn decrypt(key: Option<CryptoKeyId>, data: &[u8]) -> Result<Vec<u8>, ()>;
+
+		/// Sign a piece of data using given crypto key.
+		///
+		/// If `key` is `None`, it will attempt to use current authority key.
+		///
+		/// Returns an error if `key` is not available or does not exist.
+		fn sign(key: Option<CryptoKeyId>, data: &[u8]) -> Result<Vec<u8>, ()>;
+
+		/// Verifies that `signature` for `msg` matches given `key`.
+		///
+		/// Returns an `Ok` with `true` in case it does, `false` in case it doesn't.
+		/// Returns an error in case the key is not available or does not exist or the parameters
+		/// lengths are incorrect.
+		fn verify(key: Option<CryptoKeyId>, msg: &[u8], signature: &[u8]) -> Result<bool, ()>;
+
+		/// Returns current UNIX timestamp (in millis)
+		fn timestamp() -> Timestamp;
+
+		/// Pause the execution until `deadline` is reached.
+		fn sleep_until(deadline: Timestamp);
+
+		/// Returns a random seed.
+		///
+		/// This is a trully random non deterministic seed generated by host environment.
+		/// Obviously fine in the off-chain worker context.
+		fn random_seed() -> [u8; 32];
+
+		/// Sets a value in the local storage.
+		///
+		/// Note this storage is not part of the consensus, it's only accessible by
+		/// offchain worker tasks running on the same machine. It IS persisted between runs.
+		fn local_storage_set(key: &[u8], value: &[u8]);
+
+		/// Sets a value in the local storage if it matches current value.
+		///
+		/// Since multiple offchain workers may be running concurrently, to prevent
+		/// data races use CAS to coordinate between them.
+		///
+		/// Note this storage is not part of the consensus, it's only accessible by
+		/// offchain worker tasks running on the same machine. It IS persisted between runs.
+		fn local_storage_compare_and_set(key: &[u8], old_value: &[u8], new_value: &[u8]);
+
+		/// Gets a value from the local storage.
+		///
+		/// If the value does not exist in the storage `None` will be returned.
+		/// Note this storage is not part of the consensus, it's only accessible by
+		/// offchain worker tasks running on the same machine. It IS persisted between runs.
+		fn local_storage_get(key: &[u8]) -> Option<Vec<u8>>;
+
+		/// Initiaties a http request given HTTP verb and the URL.
+		///
+		/// Meta is a future-reserved field containing additional, parity-codec encoded parameters.
+		/// Returns the id of newly started request.
+		fn http_request_start(
+			method: &str,
+			uri: &str,
+			meta: &[u8]
+		) -> Result<HttpRequestId, ()>;
+
+		/// Append header to the request.
+		fn http_request_add_header(
+			request_id: HttpRequestId,
+			name: &str,
+			value: &str
+		) -> Result<(), ()>;
+
+		/// Write a chunk of request body.
+		///
+		/// Writing an empty chunks finalises the request.
+		/// Passing `None` as deadline blocks forever.
+		///
+		/// Returns an error in case deadline is reached or the chunk couldn't be written.
+		fn http_request_write_body(
+			request_id: HttpRequestId,
+			chunk: &[u8],
+			deadline: Option<Timestamp>
+		) -> Result<(), HttpError>;
+
+		/// Block and wait for the responses for given requests.
+		///
+		/// Returns a vector of request statuses (the len is the same as ids).
+		/// Note that if deadline is not provided the method will block indefinitely,
+		/// otherwise unready responses will produce `DeadlineReached` status.
+		///
+		/// Passing `None` as deadline blocks forever.
+		fn http_response_wait(
+			ids: &[HttpRequestId],
+			deadline: Option<Timestamp>
+		) -> Vec<HttpRequestStatus>;
+
+		/// Read all response headers.
+		///
+		/// Returns a vector of pairs `(HeaderKey, HeaderValue)`.
+		/// NOTE response headers have to be read before response body.
+		fn http_response_headers(
+			request_id: HttpRequestId
+		) -> Vec<(Vec<u8>, Vec<u8>)>;
+
+		/// Read a chunk of body response to given buffer.
+		///
+		/// Returns the number of bytes written or an error in case a deadline
+		/// is reached or server closed the connection.
+		/// If `0` is returned it means that the response has been fully consumed
+		/// and the `request_id` is now invalid.
+		/// NOTE this implies that response headers must be read before draining the body.
+		/// Passing `None` as a deadline blocks forever.
+		fn http_response_read_body(
+			request_id: HttpRequestId,
+			buffer: &mut [u8],
+			deadline: Option<Timestamp>
+		) -> Result<usize, HttpError>;
 	}
 }