Remote fetching of data

This release allows the caller to specify a SSVM_Fetch parameter that will:

• GET and return the data from the URL provided
• POST and return the data from the request object provided

This allows the caller to deal with large files without having to upload/download them. The GET and POST activities take place on the server side. The client stays light.

Examples

SSVM_Fetch in the request body (passes the response from the request and ignores any peripheral data in the body)

curl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/run/1/say' \
--header 'SSVM_Usage_Key: 83f02dd3-6440-482f-983f-78127ed6f943' \
--header 'Content-Type: application/json' \
--data-raw '{
	"SSVM_Fetch": {
		"body": "body",
		"hostname": "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_params": [1, 2]
}'

Returns

hello hello "body"

SSVM_Fetch in the request head (overrides body and any peripheral data)

curl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/run/1/say' \
--header 'SSVM_Usage_Key: 83f02dd3-6440-482f-983f-78127ed6f943' \
--header 'SSVM_Fetch: {"body": "header","hostname": "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"}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"SSVM_Fetch": {
		"body": "body",
		"hostname": "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_params": [1, 2]
}'

Returns

hello hello "header"

SSVM_Fetch in the request body; providing only a URL

curl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/run/1/say' \
--header 'SSVM_Usage_Key: 83f02dd3-6440-482f-983f-78127ed6f943' \
--header 'Content-Type: application/json' \
--data-raw '{
	"SSVM_Fetch": "https://raw.githubusercontent.com/tpmccallum/test_endpoint2/master/tim.txt",
	"function_params": [1, 2]
}'

Returns

hello Tim

SSVM_Fetch in the request header; providing only a URL

curl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/run/1/say' \
--header 'SSVM_Usage_Key: 83f02dd3-6440-482f-983f-78127ed6f943' \
--header 'SSVM_Fetch: https://raw.githubusercontent.com/tpmccallum/test_endpoint2/master/tim2.txt' \
--header 'Content-Type: application/json' \
--data-raw '{
	"SSVM_Fetch": "https://raw.githubusercontent.com/tpmccallum/test_endpoint2/master/tim.txt"
}'

Returns

hello Tim2

Note:

• SSVM_Fetch overrides other data provided and only passes the response from the fetch-able endpoint to the function being called
• Header overrides body

Updated to include authenticated calling, ephemeral storage, callback functionality (callback object can be in request header, request body or stored in DB)

This 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, putting application/json in the header's Content-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.

V1.0.0

A live RESTful API which allows end users to:

• Upload compiled .wasm executables
• Hotswap to newer compiled .wasm executables
• Get sha256 hex digest of WebAssembly executable to confirm integrity during execution
• Execute functions which reside in previously uploaded .wasm executables
• Perform function execution whilst using multipart requests to facilitate the functions input parameters
• Perform pre function execution requests
• Perform post function execution requests (callbacks)

Documentation includes:

• Videos demonstrating all current functionality
• Comprehensive RESTful API documentation including working examples
• Detailed instructions demonstrating how to build and host a new wasm-joey FaaS system

Working demonstration:

• https://rpc.ssvm.secondstate.io:8081/