fluencelabs/gitbook-docs
1
0
Fork 0
mirror of https://github.com/fluencelabs/gitbook-docs synced 2024-12-04 15:20:24 +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
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.