Introduction CYFS for Developers(Part6-1): Components(cyfs-base)

[streetycat]

Introduction CYFS for Developers(Part6): Components

I want to introduce the existed components one by one in this issue.

Overview

The components are collected as a crate in the directory src/component, and they are named with the prefix "cyfs-". Some crates have similar names. They are different crates that perform the same function together. They may implement different functions for different scenarios, or may have different levels of encapsulation. The referencer can refer to different crates according to different needs.

cyfs-base

This is the most basic component, and almost all other components depend on it.
It implement the follow functions:

1. The basic types or structures:

   • AccessString: Structures for ACL.It refers to the design of file system permission in linux.It divides users into 6 groups:

     • CurrentDevice
     • CurrentZone
     • FriendZone
     • OthersZone
     • OwnerDec
     • OthersDec
       These groups can be combined arbitrarily to get the target group that the user wants to configure permissions.
       And we can configure 3 permissions:
     • Call
     • Write
     • Read

   • Base36: Transform the BLOB with A human-readable string ignoring case. The string will be used case-insensitively, .eg:

     • Address Bar in browser
     • FileSystem of windows

   • channel: This name is used in many occasions. Here it defines the operating environment of the CYFS system. Currently, the CYFS system has 3 operating environments:

     • nightly: The integrated environment for developers.
     • beta: The public test environment for users.
     • stable: The formal version release environment.
       Different environments are independent of each other, they are connected to different MetaChains and SNs, and cannot be interconnected.

   • endpoint: Encapsulation of IpAddr, It's used to connect into the network.

   • BuckyError: Define the Results for CYFS.

   • Name: As the domain for http, we can register a readable nick name for any object.

   • paths: The req-path(similar as the URI for http) or the path in RootState

   • ports: The listening ports when the CYFS running.

   • protocol_fields: The HTTP header fields, HTTP is used at RPC between the stack(runtime/gateway) and the other services or DECApp.

   • time: Defines various standard timestamps, and the methods to convert between them

2. The framework for encode/decode:
   • RawEncode/RawDecode: Encode with binary.
   • Protobuf: Encode with protobuf
   • JSON: Encode with JSON
3. Encapsulation of the crypto library:
   • AES
   • Hash: Only for SHA256?
   • KeyPair(PrivateKey/PublicKey): RSA1024/2048/3072, and SECP256K1.
   • Signature/Verify: Signature with the KeyPair
4. The 14 standard objects:
   • Action: It seems a empty object, Maybe the design draft may not be finalized yet.
   • AppGroup: It seems a empty object, Maybe the design draft may not be finalized yet.
   • Chunk: The piece in any binary data. but there is only the Hash of the content is included in the Object system without the content itself.
   • Device: The object describing a device,it includes all the parameters used to connect each other:
     • Endpoint
     • SN
     • PN
     • Protocol version
     • And we can give it a readable name.
       All the fields is mutable, so, they are saved in Body.The Device will be publish on the MetaChain, Therefore,we should query the latest version from MetaChain when we realized that it was no longer effective.
   • Dir: The object describing a directory in filesystem.It includes some files in different sub-path, the file(even chunk) list will be included in the desc if the size is little enough, otherwise the content(file/chunk list) will be included in the body or in another file.If the content is not saved in desc, there should be a hash to verify the authenticity of the content.
   • File: The object describing a file in filesystem.It includes 3 fields:
     • File length, immutable, saved in desc
     • File hash, immutable, saved in desc
     • The contained chunks, immutable, saved in body, So,we must verify the file hash instead of the chunkids.
   • Diff: The delta between 2 file, it's usefull to describe different versions of the same file.
   • Group: It's used to describe an organization,The main fields is the administrators and members, they are all mutable,we should update it through the MetaChain or other synchronization methods.There is a issue for it.
   • People: Describing a natural person, There are only 3 fields currently:
     • name
     • icon
     • ood_list
       All the fields is mutable,and the new version will be pushed to the MetaChain.
   • Relation: It seems a empty object, Maybe the design draft may not be finalized yet.
   • Tx: It is the concept of tx in the blockchain, describing a transaction itself, the main field includes:
     • caller
     • message: transaction details
     • gas
   • UnionAccount: Joint account of both parties(Provider and Consumer) to the transaction.They transfer the initial coin and set their respective shares,As the contract progresses, the share is revised.All the updates must be signed by both, and executed on the MetaChain.Both parties are free to withdraw their share of coins.The UionAccount object only describes the account itself, not the current state of the account. It has 3 fields only:
     • left: party to the transaction
     • right: another party to the transaction
     • service type: type of the transation
       How to update/query the state of the account?Maybe we can find it on the MetaChain
   • Contract: Describe the commitment of both parties to the transaction (price, quality, etc.).
   • ProofOfService: Describe the confirmation of the final transaction quantity and quality.Provider and consumer must sign on the contract and receipt.
     When there is a dispute in the transaction, one party presents the ProofOfService signed by the other party and submits it to MetaChain for arbitration, and the transaction can be completed according to the contract.
     The design of the specific service contract is complicated and different from each other, so I need to elaborate on it in another document.By the way,The contract seems a temporary design.
   • ObjectMap: The container for objects, The ObjectId is calculate with all items, it will change when any item is updated, and we can regard the two versions before and after modification as two different objects.The ObjectMap can express three structures:
     • Map<Key, ObjectId>
     • Set
     • Diff: The delta between 2 ObjectMap, it can be stored in a file.
5. Other structures for object
   • Area: Every object should belong to a different Area, and accept the legal supervision of the corresponding Area. The Area field is set when the object is generate, and is encoded in header 40 bits of the ObjectId.
   • NamedObject: The basic trait for any Object.
   • TypelessObject: It's a shell for any Object.It collects the common fields,and it includes the object content in the form of buffer.
   • AnyNamedObject: It's a abstract shell for any Object. It can be generate from any object, and we can decode it to get the original object.It is often used with TypelessObject.
   • NDNObject: It's a shell for all unstructured data(Dir,File,Diff)
   • ObjectLink: ***I don't understand its exact design intent.***Maybe it's a reference to another Object.
   • ObjectSigns: It describes the signature information of an object, and the current signature independently signs Desc and Body respectively.I think there will be some risk,You are welcome to join the discussion.
   • UniqueId: Binary with a length of 16 bytes, We can fill the ObjectDesc with the random UniqueId when we need to distinguish the object with same fields in ObjectDesc:
     • No fields in ObjectDesc
     • The fields in ObjectDesc is same, but the ObjectBody will be update in different time.They are 2 different objects.

cyfs-base-derive

Some usefull macro is implement in this crate:
* RawEncode
* RawDecode
* ProtobufEncode
* ProtobufDecode

cyfs-base-meta

The basic structures for `MetaChain`.