diff --git a/tutorials_tutorials/add-your-own-builtin.md b/tutorials_tutorials/add-your-own-builtin.md index 9ae0bce..27c0319 100644 --- a/tutorials_tutorials/add-your-own-builtin.md +++ b/tutorials_tutorials/add-your-own-builtin.md @@ -1,14 +1,16 @@ # Add Your Own Builtins -As discussed in the [Node](../knowledge_knowledge/node/knowledge_node_services.md) section, some service functionalities useful to a large audience and such services and can be directly deployed to a peer node. The remainder of this tutorial guides you through the steps necessary to create and deploy a Builtin service. +As discussed in the [Node](../knowledge_knowledge/node/knowledge_node_services.md) section, some service functionalities have ubiquitous demand making them suitable candidates to be directly deployed to a peer node. The [Aqua distributed hash table](https://github.com/fluencelabs/fluence/tree/master/deploy/builtins/aqua-dht) \(DHT\) is an example of builtin service. The remainder of this tutorial guides you through the steps necessary to create and deploy a Builtin service. -In order to have a service available out-of-the-box with the necessary startup and scheduling scripts, we can take advantage of the Fluence [deployer feature](https://github.com/fluencelabs/fluence/tree/master/deploy) for Node native Services. This feature handles the complete deployment process including +In order to have a service available out-of-the-box with the necessary startup and scheduling scripts, we can take advantage of the Fluence [deployer feature](https://github.com/fluencelabs/fluence/tree/master/deploy) for Node native services. This feature handles the complete deployment process including * module uploads, -* service deployment, +* service deployment and * script initialization and scheduling -Note that the deployment process is a fully automated workflow requiring you to merely submit your service assets in the appropriate structure as a PR to the appropriate GitHub repository. At this point you should have a solid grasp of creating service modules and their associated configuration files. See the [Developing Modules And Services](../development_development/) section for details. +Note that the deployment process is a fully automated workflow requiring you to merely submit your service assets, i.e., Wasm modules and configuration scripts, in the appropriate format as a PR to the ??? GitHub repository. + +At this point you should have a solid grasp of creating service modules and their associated configuration files. See the [Developing Modules And Services](../development_development/) section for more details. Our first step is fork the ??? repo by clicking on the Fork button, upper right of the repo webpage, and follow the instructions to create a local copy. In your local repo copy, checkout a new branch with a new, unique branch name: @@ -16,7 +18,7 @@ Our first step is fork the ??? repo by clicking on the Fork button, upper right git checkout -b MyBranchName ``` -In your new branch create a new directory with the service name in the _builtin_ directory: +In our new branch, we create a directory with the service name in the _builtin_ directory: ```text cd builtins @@ -26,7 +28,7 @@ cd new-super-service Replace my-_new-super-service_ with your service name. -Now we can build and populate the required directory structure with your service assets. You should put your service files in the corresponding my-_new-super-service_ directory specified in config as `builtins_base_dir` +Now we can build and populate the required directory structure with your service assets. You should put your service files in the corresponding _my_-_new-super-service_ directory. **TODO: check if that applies to new repo approach.** @@ -36,11 +38,11 @@ In order to deploy a builtin service, you need * the Wasm file for each module required for the service * the blueprint file for the service -* start and scheduling scripts +* the optional start and scheduling scripts #### Blueprint -Just to recap, blueprints capture the service name and dependencies: +Blueprints capture the service name and dependencies: ```javascript // example_blueprint.json @@ -48,95 +50,33 @@ Just to recap, blueprints capture the service name and dependencies: "name": "my-new-super-service", "dependencies": [ "name:my_module_1", - "name:my_module_2" + "name:my_module_2", + "hash:Hash(my_module_3.wasm)" ] } ``` -where name specifies the service's name and _my\_module\_i_ refers to ith module created when you compiled your service code, i.e. _my\_module\_i.wasm_. Please note that dependencies may also be specified as hashes: +where -```javascript -// example_blueprint.json with hashes -{ - "name": "aqua-dht", - "dependencies": [ - "hash:558a483b1c141b66765947cf6a674abe5af2bb5b86244dfca41e5f5eb2a86e9e", - "name:aqua-dht" - ] -} -``` +* name specifies the service's name and +* dependencies list the names of the Wasm modules or the Blake3 hash of the Wasm module +In the above example, _my\_module\_i_ refers to ith module created when you compiled your service code - -Start Script - - - -Scheduling Script - - - -Putting it all together: +{% hint style="info" %} +The easiest way to get the Blake3 hash of our Wasm modules is to install the [b3sum](https://crates.io/crates/blake3) utility: ```text --- builtins - -- {service_alias} - -- scheduled - -- {script_name}_{interval_in_seconds}.air [optional] - -- blueprint.json - -- on_start.air [optional] - -- on_start.json [optional] - -- {module1_name}.wasm - -- {module1_name}_config.json - -- {module2_name}.wasm - -- {module2_name}_config.json - ... +cargo install b3sum +b3sum my_module_3.wasm ``` +{% endhint %} -In blueprint you can specify dependencies either with name or hashes but .wasm files and config should have corresponding names. `blieprint.json` example: - -Just to recap, blueprints specify the service name and module dependencies: - - - -In blueprint you can specify dependencies either with name or hashes but .wasm files and config should have corresponding names. `blieprint.json` example: - -```javascript -// blueprint.json -{ - "name": "my-new-super-service", - "dependencies": [ - "name: module_1", - "name: module_2" - ] -} -``` - -where _module\_i_ is the name of the Wasm module. Note that dependencies can be specified as string literals or hashes: - -```javascript -// blueprint.json -{ - "name": "aqua-dht", - "dependencies": [ - "hash:558a483b1c141b66765947cf6a674abe5af2bb5b86244dfca41e5f5eb2a86e9e", - "name:aqua-dht" - ] -} -``` - -So modules and configs names should look like this: - -```text --- aqua-dht.wasm --- aqua-dht_config.json --- 558a483b1c141b66765947cf6a674abe5af2bb5b86244dfca41e5f5eb2a86e9e.wasm --- 558a483b1c141b66765947cf6a674abe5af2bb5b86244dfca41e5f5eb2a86e9e_config.json -``` +If you decide to use the hash approach, please use the hash for the config files names as well \(see below\). #### **Start Script** -Start scripts, which are optional, execute once after service deployment or node restarts and are submitted as _air_ files and may be accompanied by a json file containing the necessary parameters. +Start scripts, which are optional, execute once after service deployment or node restarts and are submitted as _air_ files and may be accompanied by a _json_ file containing the necessary parameters. ```text ;; on_start.air @@ -149,7 +89,7 @@ Start scripts, which are optional, execute once after service deployment or node and the associated data file: ```javascript -// on_start.json +// on_start.json data for on_start.air { "variable1" : "some_string", "variable2" : 5, @@ -180,10 +120,25 @@ Now that we got our requirements covered, we can populate the directory structur -- on_start.json [optional] -- {module1_name}.wasm -- {module1_name}_config.json - -- {module2_name}.wasm - -- {module2_name}_config.json + -- Hash(module2_name.wasm).wasm + -- Hash(module2_name.wasm)_config.json ... ``` -can we call service _alias just service name._ +For a complete example, please see the [aqua-dht](https://github.com/fluencelabs/fluence/tree/master/deploy/builtins/aqua-dht) builtin: + +```text +fluence + --deploy + --builtins + --aqua-dht + -aqua-dht.wasm + -aqua-dht_config.json + -blueprint.json + -scheduled + -sqlite3.wasm + -sqlite3_config.json +``` + +which based on the [eponymous](https://github.com/fluencelabs/aqua-dht) service project.