The zone-simulator
is a useful tool in coding. It can simulate two zones in a single process, with two built-in oods, and each ood has two devices. It is very convenient to use this tool to run multiple DECApp
instances on the local machine at the same time during the development and debugging phase. Just configure different RPC
ports to connect to different devices when each instance opens SharedCyfsStack
to access the emulator environment.
Zone1 | <--> | Zone2 | ||||
---|---|---|---|---|---|---|
People1 | People2 | |||||
Device1 | <--> | ood1 | ood2 | <--> | Device1 | |
Device2 | <--> | <--> | Device2 |
The usage is as follows(Excerpted from a previous document on the official website):
- Mnemonic
- By default,
zone-simulator
derives all people and device information from mnemonics through thebip
protocol, so the same set of mnemonics generates the same zone configuration information every time. - A random mnemonic will be generated by default when
zone-simulator
is started first time, and saved in{cyfs-root}/etc/zone-simulator/mnemonic
; this configuration will be loaded each startup, if you need to create new zone desc information, then delete this configuration file. - the debug version is slow to derive the key from the mnemonic, and it usually takes one to two minutes to complete the execution.
- Zone desc
zone contains follow infomation:
- 2 people desc, representing 2
zone
s respectively. - 2 ood desc, representing the ood in 2
zone
s respectively. - The 4 device desc represent 2 devices in each
zone
, and the ood in same zone constitutes an independentzone
.
When the zone-simulator is started, the above information will be written into the {cyfs-root}/etc/zone-simulator/desc_list
directory, which corresponds to the mnemonic one-to-one, and the desc list generated by the same set of mnemonics will are the same, and development and testing can directly rely on this information.
For example, the mnemonic is below:
million used drastic castle during top category wood street visa steak bachelor
The generated desc list is as follows:
zone1 as follows:
people:5r4MYfFFQetBPDyeuBuDxPT7zowk9497SbpMQsZK2G19
ood:5aSixgLq9LVWbPByjRYgyjGicXtCN5S1nF1DMKZygLRE
device1:5aSixgPFg7R48VSo2b9PXcSHofK3TUFUcHnHbtmB7fJr
device2:5aSixgRaonSm1qWeCh8kNNrPGaB6pbETsqoN4Zb5Ev3H
zone2 as follows:
people:5r4MYfFGppKJXEjLvsgbKsibmTVLFZhL5cuZdEcXSr68
ood:5aSixgM12wHBfJBW1Q9n4xv1c5cu5g8hSxbrkhAQoojq
device1:5aSixgPdH5stj9pHrRVGXPNKiyrPsy8932BEr3zwFhXF
device2:5aSixgRx45jDU4Fg4ijYo3Yfo6RajtKSHgnGCVJUnk65
The above device_id and people_id can be directly used as the target of router and other interfaces to interact with the corresponding protocol stack.
For example, put_object to ood1
:
const ood1 = DeviceId.from_base_58('5aSixgLq9LVWbPByjRYgyjGicXtCN5S1nF1DMKZygLRE').unwrap();
const target = ood1.object_id;
stack.put_object({
...,
target
})
You can directly use the people_id of zone1 as the target:
const people1 = PeopleId.from_base_58('5r4MYfFFQetBPDyeuBuDxPT7zowk9497SbpMQsZK2G19').unwrap();
const target = people1.object_id;
stack.put_object({
...,
target
})
- Ports for
RPC
2 zones, each zone contains 1 ood + 2 devices, so there are six stacks in total. In order to facilitate external sdk calls, fixed ports are used, and the allocation is as follows:
device | bdt-port | http-port | ws-port |
---|---|---|---|
zone1-ood1 | 20001 | 21000 | 21001 |
zone1-device1 | 20002 | 21002 | 21003 |
zone1-device2 | 20003 | 21004 | 21005 |
zone2-ood1 | 20010 | 21010 | 21011 |
zone2-device1 | 20011 | 21012 | 21013 |
zone2-device2 | 20012 | 21014 | 21015 |
The http-port
and ws-port
can be used as the service interface of the local SharedObjectStack, we can open SharedObjectStack
directly with them, and pass it to the corresponding interface.
For example, if you want to use the protocol stack of zone1-device2, you can open SharedCyfsStack
as follow:
const param = SharedObjectStackParam.new_with_ws_event_ports(21004, 21005).unwrap();
const stack = SharedObjectStack.open(param);
await stack.online();
- Scene simulation
The above two zones can simulate most of the interaction scenarios in cyfs:
- Interaction between two devices in same zone, you can select device1 and device2 in the same zone.
- Interaction between the device and ood in same zone, you can choose any device+ood in the same zone.
- Cross-zone interaction, select 1 device in each
zone
(zone1 or zone2). - Cross-zone service, use zone1 as client and zone2 as server, then use zone1-device1+ood2, and dec-service can be connected to ood2.
- Command line
There are 2 commands, and some auxiliary information can be generated:
- random: Generate a random set of mnemonic words。
shell> zone-simulator.exe --random
random mnemonic as follows:
side act dilemma super open tonight shallow wrong brother various potato punch
- dump: Dump the desc+sec information of
people/ood/device
generated by the current mnemonic, and save it in the default directory{cyfs}/etc/zone-simulator/
, user1 indicates the information related to zone1, and user2 indicates the information related to zone2. These information can be placed under{cyfs}/etc/desc
for direct use bygateway
,runtime
or zone-stack etc. Note: The generated information is not on the chain. If you rely on the chaining logic, you must use the desc-tool to be on the chain.。
After solving most of the errors in the zone-simulator
environment, We can deploy the project to the test environment and start testing:
- There are 2 environments currently used for testing, they are
nightly
andbeta
, and the stable environment has not yet been launched. The target environment for deployment depends on the environment ofcyfs-tool
,cyfs-runtime
andOOD
, they must be the same environment, eithernightly
orbeta
. - The
cyfs deploy
command is used to deploy a project, It should run in the same directory as the project filecyfs.config.json
, it will take a long time. Here we introduce the contents of thecyfs.config.json
file in detail:
{
"app_name": "your project name",
"version": "1.0.0", // version with 3 fields
"description": "descript your project",
"icon": "url for your icon that has published.cyfs://",
"service": { // configuration for service
"pack": ["directory1", "directory2", "..."], // A list of directories for source code in server-side, which will be packaged together using same relative paths
"type": "node", // type of your project: nodejs or native
"dist_targets": ["x86_64-pc-windows-msvc", "x86_64-unknown-linux-gnu"], // target os
"app_config": {
"default": "service_package.cfg" // configuration for service, introduce later
},
"app_dependent_config": {
"default": "dependent.cfg" // Dependent configuration, which may depend on other `DECApp`
},
"app_acl_config": {
"default": "acl.cfg" // The permissions required by `DECApp`, and the permissions configuration opened to others
}
},
"web": { // configuration for web
"folder": "src/www/dist", // Directory of the source code for web
"entry": "index.html" // Entry webpage
},
"dist": "dist", // The directory for the packaged resources
"owner_config": ".cyfs\\owner.json", // Owner of `DECApp`, which will be generated when using `cyfs-tool` to build the project, usually configures the identity file exported by the developer environment. It can be modified with the `cyfs modify` command, but it will become a new project after the change, and all information including `DecAppId` and historical versions will be changed, pay attention to synchronously modify related configurations.
"ext_info": {
"cyfs-app-store": { // Configuration displayed on `AppStore`
"tag": ["tag1", "tag2", "..."], // Add some tags
"community": ["your community name"],
"releasedate": {
"1.2.20": "2022-11-14" // the version history
}
}
},
"app_id": "9tGpLNna8UVtPYCfV1LbRN2Bqa5G9vRBKhDhZxxxxxxx", // your `DecAppId`
"config_version": 1 // version of the format used by the config file?
}
Fields of service_package.cfg
as follow:
{
"id": "your readable project name", // unique?
"version": "1.0.0", // verison with 3 fields
"install": ["cmd1", "cmd2", "..."], // Commands in order for install the `DECApp`
"start": "command", // Command to start the `DECApp`
"stop": "command", // Command to stop the `DECApp`
"status": "command", // Command to query the status the `DECApp`
"executable": [] // ?
}
You can execute cyfs deploy
to publish your DECApp
after the above information is configured correctly. The URL
to install DECApp
will show in the last line. Now others can also get your latest version. **If you are not ready for others, you can separate the development People
from the publish People
, and use the People
environment to deploy your DECApp
. **
- Open the
AppStore
on the browser, and install theDECApp
with theURL
generated bycyfs deploy
. Now you can use and check that yourDECApp
works correctly.