aqua-lib/builtin.aqua

400 lines
14 KiB
Plaintext
Raw Normal View History

-- Default public interface of Fluence nodes
aqua Builtin declares *
2021-04-29 12:22:39 +00:00
alias Field : []string
alias Argument : []string
alias Bytes : []u8
alias PeerId : string
alias Pairs : [][]string
alias Base58String : string
2021-07-22 16:36:51 +00:00
alias Hash : string
alias IPLDBlueprint : string
alias CID : string
2023-07-17 12:13:20 +00:00
alias Path : string
2021-04-29 12:22:39 +00:00
data Service:
id: string
blueprint_id: string
-- `spell` or `service`
service_type: string
2021-04-29 12:22:39 +00:00
owner_id: string
aliases: []string
worker_id: string
2021-04-29 12:22:39 +00:00
data FunctionSignature:
arguments: []Argument
name: string
output_types: []string
data RecordType:
fields: []Field
id: u64
name: string
data Interface:
function_signatures: []FunctionSignature
record_types: []RecordType
data Info:
external_addresses: []string
node_version: string
air_version: string
2023-04-03 10:31:30 +00:00
spell_version: string
allowed_binaries: []string
2021-04-29 12:22:39 +00:00
data ModuleWASIConfig:
envs: ?Pairs
mapped_dirs: ?Pairs
mounted_binaries: ?Pairs
2021-04-29 12:22:39 +00:00
data ModuleConfig:
name: string
mem_pages_count: ?u32
max_heap_size: ?string
logger_enabled: ?bool
logging_mask: ?i32
wasi: ?ModuleWASIConfig
2021-04-29 12:22:39 +00:00
data Module:
name: string
hash: string
config: ModuleConfig
data Blueprint:
id: string
name: string
dependencies: []CID
2021-04-29 12:22:39 +00:00
data ScriptInfo:
id: string
src: string
failures: u32
interval: string
owner: string
data Contact:
peer_id: string
addresses: []string
2022-12-26 11:49:58 +00:00
-- A collection of measurements of a stat.
-- `avg` and `total` fields are computed over all measured stats and
-- `series` stores only several last measurements. The number of measurements
-- is configured on each peer.
data SeriesStat:
avg: f64
series: []f64
total: f64
data Stats:
-- Number of successful request
success_req_count: u64
-- Number of failed request
failed_req_count: u64
-- Duration of call execution in seconds
call_time_sec: SeriesStat
-- Amount of addintionally allocated memory after a call
memory_deltas_bytes: SeriesStat
-- Timestamps of the last measurments
timestamps: []u64
data FunctionStat:
name: string
-- Series contain last measurements that were taken from last N calls to this function
stats: Stats
data ServiceStat:
-- Stats for the requested service in total.
-- Series contain last measurements that were taken from last N calls to the service
total_stats: Stats
-- Stats for each interface function of the service
functions_stats: []FunctionStat
data StatResult:
status: bool
error: string
result: ?ServiceStat
data MemoryStat:
-- module name
name: string
memory_size_bytes: u64
max_memory_size_bytes: u64
2021-04-29 12:22:39 +00:00
service Op("op"):
-- does nothing
noop()
2021-07-02 16:00:05 +00:00
-- returns length of the passed array
array_length(array: []string) -> u32
-- takes any number of arguments and wraps them into a single array
-- see the doc on varargs https://doc.fluence.dev/aqua-book/libraries/aqua-lib#functions-with-a-variable-number-of-arguments
array(a: string, b: string, c: string, d: string) -> []string
-- takes any number of arrays and flattens them by concatenating
-- see the doc on varargs https://doc.fluence.dev/aqua-book/libraries/aqua-lib#functions-with-a-variable-number-of-arguments
concat(a: []string, b: []string, c: []string, d: []string) -> []string
-- takes a single argument and returns it back
identity(s: ?string) -> ?string
-- encodes string's utf8 bytes as base58
string_to_b58(s: string) -> Base58String
-- decodes base58 to bytes to utf8 string
-- throws error on invalid UTF8
string_from_b58(b: Base58String) -> string
-- encodes bytes as base58
bytes_to_b58(bs: []u8) -> Base58String
-- decodes base58 to bytes
bytes_from_b58(b: Base58String) -> []u8
-- Applies SHA256 to the given string
-- Argument: s - string to apply sha256 to (hash is applied to utf8 bytes of s)
-- Returns: returns sha256 multihash encoded as base58
sha256_string(s: string) -> Base58String
2021-07-22 16:36:51 +00:00
-- concatenate strings (in AIR it takes any number of arguments)
concat_strings(a: string, b: string) -> string
2021-04-29 12:22:39 +00:00
service Peer("peer"):
-- Get information about the peer
identify() -> Info
2021-04-29 12:22:39 +00:00
-- Get Unix timestamp in milliseconds
timestamp_ms() -> u64
2021-04-29 12:22:39 +00:00
-- Get Unix timestamp in seconds
timestamp_sec() -> u64
2021-04-29 12:22:39 +00:00
-- Blocks for the given number of milliseconds. Meant to be used within `par` blocks.
-- message is returned after duration has passed
timeout(duration_ms: u64, message: string) -> string
2021-11-21 15:48:47 +00:00
---- Low level functions for accessing connection pool
-- Checks if there is a direct connection to the peer identified by a given PeerId
-- Argument: PeerId id of the peer to check if there's a connection with
-- Returns: bool - true if connected to the peer, false otherwise
-- NOTE:
-- This is a very low-level function, it most likely won't fit your goals.
-- It's almost always better to use race pattern to check connectivity.
-- See https://doc.fluence.dev/aqua-book/language/flow/parallel#timeout-and-race-patterns
is_connected(peer: PeerId) -> bool
-- Initiates a connection to the specified peer
-- Arguments:
-- id - id of the target peer
-- multiaddrs an array of target peer's addresses
-- Returns: bool - true if connection was successful
-- NOTE:
-- This is a low-level function, it most likely won't fit your goals.
-- Most often you just need to use `on id:` and connection will be established automatically.
connect(id: PeerId, multiaddrs: []string) -> bool
-- Returns known multiaddresses of a peer
-- Argument: PeerId id of the target peer
-- Returns:
-- Contact - if target peer is connected to current peer,
-- return data structure with multiaddresses inside, and nil otherwise.
get_contact(peer: PeerId) -> ?Contact
2021-04-29 12:22:39 +00:00
service Kademlia("kad"):
-- Instructs node to return the locally-known nodes
-- in the Kademlia neighborhood for a given key
-- Arguments:
-- key base58 string
-- already_hashed default false; if set to true, key is considered to be a SHA256 multihash
-- count default 20; limits number of returned nodes
neighborhood(key: Base58String, already_hashed: ?bool, count: ?u32) -> []PeerId
-- Merges given lists and sorts them by distance to target
-- Arguments:
-- target base58 string; result is sorted by XOR distance to target
-- left list of base58 strings
-- right list of base58 strings
-- count how many items to return; default 20
-- Returns: list of base58 strings sorted by distance to target; list will contain at most count elements
merge(target: Base58String, left: []string, right: []string, count: ?u32) -> []string
2021-04-29 12:22:39 +00:00
service Srv("srv"):
-- Used to create a service on a certain node
-- Arguments:
-- blueprint_id ID of the blueprint that has been added to the node specified in the service call by the dist add_blueprint service.
2021-04-29 12:22:39 +00:00
-- Returns: service_id the service ID of the created service.
create(blueprint_id: string) -> string
2021-04-29 12:22:39 +00:00
2021-04-29 15:01:10 +00:00
-- Used to remove a service from a certain node
-- Arguments:
-- service_id ID of the service to remove
remove(service_id: string)
2021-04-29 15:01:10 +00:00
2021-04-29 12:22:39 +00:00
-- Returns a list of services running on a peer
list() -> []Service
2021-04-29 12:22:39 +00:00
-- Adds an alias on service, so, service could be called
-- not only by service_id but by alias as well.
-- Arguments:
-- alias - settable service name
-- service_id ID of the service whose interface you want to name.
add_alias(alias: string, service_id: string)
2021-04-29 12:22:39 +00:00
-- Resolves given alias to a service id
-- If there's no such alias, throws an error
-- Returns: service id associated with the given alias
resolve_alias(alias: string) -> string
-- Resolves given alias to a service id
-- If there's no such alias, returns nil
-- Returns: service id associated with the given alias or nil
resolve_alias_opt(alias: string) -> ?string
2021-04-29 12:22:39 +00:00
-- Retrieves the functional interface of a service running
-- on the node specified in the service call
-- Argument: service_id ID of the service whose interface you want to retrieve.
2021-06-18 16:53:57 +00:00
get_interface(service_id: string) -> Interface
-- Retrieves information about service
-- Argument: service_id ID or alias of the service
info(service_id: string) -> Service
2021-04-29 12:22:39 +00:00
service Dist("dist"):
-- Constructs a ModuleConfig structure
-- Arguments:
-- module_name - import name of the module
-- mem_pages_count - Maximum memory size accessible by a module in Wasm pages (64 Kb)
-- logger_enabled - Defines whether Marine should provide a special host log_utf8_string function for this module
-- preopened_files - Files available for this module. Module can access only files from this list
-- envs - environment variables available for this module
-- mapped_dirs - Directory mapping, e.g. [["/sites", "./web/data"]] so all
-- reads & writes to /sites will actually to go ./web/data
-- mounted_binaries - Mapping of host binaries available to call from module,
-- e.g. [["curl", "/usr/bin/curl"]] will allow module to
-- call /usr/bin/curl binary as function 'curl'
-- logging_mask - Binary mask to enable & disable logging targets. Targets are
-- configured in WasmLoggerBuilder::with_target_map
-- mem_pages_count - (deprecated) Maximum memory size accessible by a module in Wasm pages (64 Kb)
-- max_heap_size - Maximum module heap size, in bytes
make_module_config(name: string, mem_pages_count: ?u32, max_heap_size: ?string, logger_enabled: ?bool, preopened_files: ?[]string, envs: ?Pairs, mapped_dirs: ?Pairs, mounted_binaries: ?Pairs, logging_mask: ?i32) -> ModuleConfig
2021-07-05 12:26:22 +00:00
2021-07-22 16:36:51 +00:00
-- Constructs a ModuleConfig structure
-- Arguments:
-- module_name - import name of the module
default_module_config(module_name: string) -> ModuleConfig
2021-07-05 12:26:22 +00:00
-- Used to add modules to the node specified in the service call
-- Arguments:
-- bytes a base64 string containing the .wasm module to add.
-- config module info
-- Returns: blake3 hash of the module
add_module(wasm_b56_content: Bytes, conf: ModuleConfig) -> string
2021-07-22 16:36:51 +00:00
-- Adds module by copying it from Particle Vault directory
-- Arguments:
-- path path or a filename
-- config - module config
2023-07-17 12:13:20 +00:00
add_module_from_vault(path: Path, config: ModuleConfig) -> Hash
2021-07-22 16:36:51 +00:00
2021-04-29 12:22:39 +00:00
-- Get a list of modules available on the node
list_modules() -> []Module
2021-04-29 12:22:39 +00:00
-- Get the interface of a module
2021-12-27 12:17:14 +00:00
get_module_interface(module_hash: string) -> Interface
2021-04-29 12:22:39 +00:00
-- Creates IPLD Blueprint structure from blueprint name and dependencies (modules)
make_blueprint(name: string, dependencies: []CID) -> IPLDBlueprint
-- Add an IPLD blueprint to the node
add_blueprint(blueprint: IPLDBlueprint) -> string
-- Loads blueprint by copying it from Particle Vault directory
-- Arguments:
-- blueprint_path path in Particle Vault
2023-07-17 12:13:20 +00:00
load_blueprint(blueprint_path: Path) -> IPLDBlueprint
2021-04-29 12:22:39 +00:00
-- Used to get the blueprints available on the node specified in the service call.
-- A blueprint is an object of the following structure
list_blueprints() -> []Blueprint
-- Get a single blueprint
get_blueprint(blueprint_id: string) -> Blueprint
2021-04-29 12:22:39 +00:00
service Script("script"):
-- Adds the given script to a node
-- Arguments:
-- air_script - raw AIR script without any undefined variables
-- interval - time to next run of the script in seconds
-- - if set, script will be ran once in the interval
-- - if not set, script will be ran only once
-- (NOTE: an actual interval may vary by up to 3 seconds)
2022-04-25 13:21:02 +00:00
add(air_script: string, interval: ?u64) -> string
2021-04-29 12:22:39 +00:00
-- Adds the script from the given path to a node
-- Arguments:
-- path - path to the AIR script without any undefined variables in the particle file vault
-- interval - time to next run of the script in seconds
-- - if set, script will be ran once in the interval
-- - if not set, script will be ran only once
-- (NOTE: an actual interval may vary by up to 3 seconds)
2023-07-17 12:13:20 +00:00
add_from_vault(path: Path, interval: ?u64) -> string
-- Removes recurring script from a node. Only the creator of the script can delete it
remove(script_id: string) -> bool
2021-04-29 12:22:39 +00:00
-- Returns a list of existing scripts on the node.
-- Each object in the list is of the following structure
list() -> []ScriptInfo
2021-12-13 15:38:57 +00:00
2022-02-04 18:18:03 +00:00
data SignResult:
-- Was call successful or not
success: bool
-- Error message. Will be null if the call is successful
error: ?string
-- Signature as byte array. Will be null if the call is not successful
signature: ?[]u8
2021-12-13 15:38:57 +00:00
service Sig("sig"):
-- Signs data with the service's private key.
2022-02-04 18:18:03 +00:00
-- Depending on implementation the service might check call params to restrict usage for security reasons.
-- By default it is only allowed to be used on the same peer the particle was initiated
-- and accepts data only from the following sources:
2021-12-13 15:38:57 +00:00
-- trust-graph.get_trust_bytes
-- trust-graph.get_revocation_bytes
-- registry.get_key_bytes (for FluenceJS only)
2021-12-13 15:38:57 +00:00
-- registry.get_record_bytes
-- registry.get_record_metadata_bytes
2021-12-13 15:38:57 +00:00
-- Argument: data - byte array to sign
2022-02-04 18:18:03 +00:00
-- Returns: signature as SignResult structure
sign(data: []u8) -> SignResult
2021-12-13 15:38:57 +00:00
2022-02-04 18:18:03 +00:00
-- Given the data and signature both as byte arrays, returns true if the signature is correct, false otherwise.
2021-12-13 15:38:57 +00:00
verify(signature: []u8, data: []u8) -> bool
2022-02-04 18:18:03 +00:00
-- Gets the peer id of the service's key pair.
get_peer_id() -> string
-- Available only on rust peers
2022-12-26 11:49:58 +00:00
-- Aquire service statistic
service Stat("stat"):
-- Detailed stats for the service and its interface functions
service_stat(service_id: string) -> StatResult
-- The amount of memeory allocated for each module of the service.
service_memory(service_id: string) -> []MemoryStat
-- Service for debugging purposes only
service Debug("debug"):
-- Convert any object into a string
stringify(o: ) -> string
2023-05-30 14:20:18 +00:00
service Console("run-console"):
print(any: )
2023-07-17 12:13:20 +00:00
-- Particle File Vault
service Vault("vault"):
-- Puts data into the vault and returns virtual path
put(data: string) -> Path
-- Returns the content of the file from the vault
cat(path: Path) -> string