2.2 Introduction CYFS for Developers: DECApp debugging and deployment

[streetycat]

DECApp debugging and deployment

zone-simulator

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):

1. Mnemonic

• By default, zone-simulator derives all people and device information from mnemonics through the bip 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.

2. Zone desc

zone contains follow infomation：

• 2 people desc, representing 2 zones respectively.
• 2 ood desc, representing the ood in 2 zones respectively.
• The 4 device desc represent 2 devices in each zone, and the ood in same zone constitutes an independent zone.

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
})

3. 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();

4. 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.

5. 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 by gateway, 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.。

Deploy your project

After solving most of the errors in the zone-simulator environment, We can deploy the project to the test environment and start testing:

1. There are 2 environments currently used for testing, they are nightly and beta, and the stable environment has not yet been launched. The target environment for deployment depends on the environment of cyfs-tool, cyfs-runtime and OOD, they must be the same environment, either nightly or beta.
2. The cyfs deploy command is used to deploy a project, It should run in the same directory as the project file cyfs.config.json, it will take a long time. Here we introduce the contents of the cyfs.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. **

3. Open the AppStore on the browser, and install the DECApp with the URL generated by cyfs deploy. Now you can use and check that your DECApp works correctly.