fluencelabs/gitbook-docs
1
0
Fork 0
mirror of https://github.com/fluencelabs/gitbook-docs synced 2025-04-24 15:32:18 +00:00
Code Issues Projects Releases Wiki Activity

GitBook: [builtins] 56 pages modified

Browse Source
This commit is contained in:
boneyard93501 2021-06-21 21:24:43 +00:00 committed by gitbook-bot
parent 4d4b12e118
commit 774d8a7b36
No known key found for this signature in database
GPG Key ID: 07D2180C7B12D0FF
1 changed files with 42 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
tutorials_tutorials/add-your-own-builtin.md
View File

@ -1,14 +1,16 @@
# Add Your Own Builtins # 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, * module uploads,
* service deployment, * service deployment and
* script initialization and scheduling * 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: 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 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 ```text
cd builtins cd builtins
@ -26,7 +28,7 @@ cd new-super-service
Replace my-_new-super-service_ with your service name. 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.** **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 Wasm file for each module required for the service
* the blueprint file for the service * the blueprint file for the service
* start and scheduling scripts * the optional start and scheduling scripts
#### Blueprint #### Blueprint
Just to recap, blueprints capture the service name and dependencies: Blueprints capture the service name and dependencies:
```javascript ```javascript
// example_blueprint.json // example_blueprint.json
@ -48,95 +50,33 @@ Just to recap, blueprints capture the service name and dependencies:
"name": "my-new-super-service", "name": "my-new-super-service",
"dependencies": [ "dependencies": [
"name:my_module_1", "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 * name specifies the service's name and
// example_blueprint.json with hashes * dependencies list the names of the Wasm modules or the Blake3 hash of the Wasm module
{
"name": "aqua-dht",
"dependencies": [
"hash:558a483b1c141b66765947cf6a674abe5af2bb5b86244dfca41e5f5eb2a86e9e",
"name:aqua-dht"
]
}
```
In the above example, _my\_module\_i_ refers to ith module created when you compiled your service code
{% hint style="info" %}
Start Script The easiest way to get the Blake3 hash of our Wasm modules is to install the [b3sum](https://crates.io/crates/blake3) utility:
Scheduling Script
Putting it all together:
```text ```text
-- builtins cargo install b3sum
-- {service_alias} b3sum my_module_3.wasm
-- 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
...
``` ```
{% endhint %}
In blueprint you can specify dependencies either with name or hashes but .wasm files and config should have corresponding names. `blieprint.json` example: If you decide to use the hash approach, please use the hash for the config files names as well \(see below\).
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
```
#### **Start Script** #### **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 ```text
;; on_start.air ;; on_start.air
@ -149,7 +89,7 @@ Start scripts, which are optional, execute once after service deployment or node
and the associated data file: and the associated data file:
```javascript ```javascript
// on_start.json // on_start.json data for on_start.air
{ {
"variable1" : "some_string", "variable1" : "some_string",
"variable2" : 5, "variable2" : 5,
@ -180,10 +120,25 @@ Now that we got our requirements covered, we can populate the directory structur
-- on_start.json [optional] -- on_start.json [optional]
-- {module1_name}.wasm -- {module1_name}.wasm
-- {module1_name}_config.json -- {module1_name}_config.json
-- {module2_name}.wasm -- Hash(module2_name.wasm).wasm
-- {module2_name}_config.json -- 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.