Updated to include authenticated calling, ephemeral storage, callback functionality (callback object can be in request header, request body or stored in DB)
Pre-releaseThis release implements the following new features.
Callbacks
- Allows user to specify a callback object as part of a request.
- Callback objects can be placed in the request header i.e.
--header SSVM_Callback: {hostname ... port ... etc.}
- Callback objects can be placed in the request body i.e.
{
"SSVM_Callback": {
"hostname": "dev.rpc.ssvm.secondstate.io",
"path": "/api/run/1/say",
"method": "POST",
"port": 8081,
"headers": {
"Content-Type": "text/plain",
"SSVM_Usage_Key": "83f02dd3-6440-482f-983f-78127ed6f943"
}
},
"Function_Parameters": [1, 2, 3, 4]
}
- Callback objects can be stored permanently in Joey's DB via a RESTful API endpoint.
- A Callback in the header overrides a Callback in the body and a Callback in the DB.
- A Callback in the body overrides a Callback in the DB.
- If no other Callback objects are provided in the request and there is a Callback object in the DB, that DB Callback will execute regardless.
- A blank Callback object in the header or the body can negate the Callback that is stored in the DB.
Mime types
- When calling a function for execution, the caller must specify the Mime type in the request header i.e.
application/json
,application/octet-stream
,text/plain
and the data in the body of the request must match this declaration. For example, puttingapplication/json
in the header'sContent-Type
field and putting non-valid JSON i.e.text/plain
in the body will not work.
Function parameters and return types
Multipart
The /api/multipart/run/:wasm_id/:function_name
endpoint will take any combination of multipart/form-data
and will return a string (to the caller).
String
The /api/run/:wasm_id/:function_name
endpoint will take application/json
, application/octet-stream
or text/plain
as input and will return a string (to the caller).
Bytes
The /api/run/:wasm_id/:function_name/bytes
endpoint will take application/json
, application/octet-stream
or text/plain
as input and will return a byte array
Authenticated calling
Private
If a Wasm executable is for private use, the caller can make Joey generate a couple of keys (at the time when the Wasm executable is uploaded). For example, if the following header (SSVM_Create_Usage_Key
) key is set to true in the request, the keys will be generated.
curl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/executables' \
--header 'Content-Type: application/octet-stream' \
--header 'SSVM_Description: Private Wasm File' \
--header 'SSVM_Create_Usage_Key: true' \
--data-binary '@/Users/tpmccallum/hello_bg.wasm'
The above code will return the following response
{
"wasm_id": 16,
"wasm_sha256": "0xfb413547a8aba56d0349603a7989e269f3846245e51804932b3e02bc0be4b665",
"usage_key": "a038c28b-0e47-42e3-8686-be4c4d7f729b",
"admin_key": "87d6edf0-52de-48fa-a4b2-0d035e5dc70a"
}
Note the usage_key
and admin_key
.
Public
On the contrary, Wasm executables that are set into the system with no mention of SSVM_Create_Usage_Key
are set to public by default. For example, the following request returns the generic zeroed out usage key.
curl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/executables' \
--header 'Content-Type: application/octet-stream' \
--header 'SSVM_Description: Private Wasm File' \
--data-binary '@/Users/tpmccallum/hello_bg.wasm'
{
"wasm_id": 17,
"wasm_sha256": "0xfb413547a8aba56d0349603a7989e269f3846245e51804932b3e02bc0be4b665",
"usage_key": "00000000-0000-0000-0000-000000000000",
"admin_key": "8741ec91-79d4-4718-bce9-d073438ea582"
}
Switching between private and public
To make a public Wasm executable private, simply perform the following RESTful (PUT
) request
curl --location --request PUT 'https://rpc.ssvm.secondstate.io:8081/api/keys/17/usage_key' \
--header 'SSVM_Admin_Key: 8741ec91-79d4-4718-bce9-d073438ea582'
The above request will return a fresh key as shown below.
{
"SSVM_Usage_Key": "c031f2c8-dada-4eff-9a92-8bd63011c7c1"
}
This PUT
request is also a great way to refresh keys i.e. change who can access a Wasm executable, after a hackathon or temporary training exercise etc.
To make a private Wasm executable public, simply perform the following RESTful DELETE
request
curl --location --request DELETE 'https://rpc.ssvm.secondstate.io:8081/api/keys/17/usage_key' \
--header 'SSVM_Admin_Key: 8741ec91-79d4-4718-bce9-d073438ea582'
Ephemeral storage
- Allows users to quickly store ephemeral information via a RESTful endpoint (no Wasm or Rust required). This is useful for pooling information from IoT sensors or performing tasks such as quickly gathering information per second which is then placed in a batch which may be processed each 60 seconds etc.
- Allows users to quickly retrieve ephemeral information via RESTful endpoint.
- Any ephemeral information is saved for up to 1 hour. If the ephemeral information (at the specific key) is updated then the 1 hour limit is restarted.