4 releases
0.0.2-alpha.6 | Mar 21, 2024 |
---|---|
0.0.2-alpha.3 | Mar 20, 2024 |
0.0.2-alpha.2 | Jan 30, 2024 |
#2201 in Magic Beans
2,943 downloads per month
Used in 2 crates
(via dotrain)
155KB
3.5K
SLoC
Rain Metadata Tooling
A library that provides all the toolings and utilities in order to work with RainLanguage metadata. Dotrain LSP/compiler, Rain Orderbook, etc are a few examples to mention that use this library under the hood.
Also provides CLI app (executable binary) to generate desireable Rain cbor encoded metadata based on Metadata Specs which for example is used in Rain deployment CI.
Features
cli
and json-schema
features are default however, in most cases non of the features are needed for using the lib crate, so they can be disabled by using default-features = false
, just be aware that cli
feature is required for building the binary.
cli
: A clap based CLI crate for functionalities of this library, this feature has tokio dependency with features enabled that are compatible forwasm
family target builds. Enabling this feature will also enablejson-schema
feature, This feature is required for building the binary crate.json-schema
: Enables implementation of Json Schema for different types of Rain meta.tokio-full
: Installs tokio with full features which is a dependency ofcli
feature, this allows for multi-threading of the CLI app, however it results in erroneous builds forwasm
target family as explained in tokio docs, this feature is only effective for binary crate and using it for lib crate just installs tokio with its full features as a dependency as the entire lib crate doesn't depend on tokio. This is because tokio is only used as a runtime for binray crate.
CLI (Binary Crate)
Tooling and utilities for RainLanguage metadata.
Usage: rain-metadata <COMMAND>
Commands:
schema command related to meta json schema
validate command for validating a meta
magic command related to rain magic numbers
build command for building rain meta
solc command related to solc artifacts
subgraph command related to subgraphs
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
Examples
Encode/Decode
Create a meta item and cbor encode/decode it:
let authoring_meta_content = r#"[
{
"word": "stack",
"description": "Copies an existing value from the stack.",
"operandParserOffset": 16
},
{
"word": "constant",
"description": "Copies a constant value onto the stack.",
"operandParserOffset": 16
}
]"#;
let authoring_meta: AuthoringMeta = serde_json::from_str(authoring_meta_content)?;
// abi encode the authoring meta with performing validation
let authoring_meta_abi_encoded = authoring_meta.abi_encode_validate()?;
// Constructing a RainMeta item (cbor map)
let meta_map = RainMetaDocumentV1Item {
payload: serde_bytes::ByteBuf::from(authoring_meta_abi_encoded),
magic: KnownMagic::AuthoringMetaV1,
content_type: ContentType::Cbor,
content_encoding: ContentEncoding::None,
content_language: ContentLanguage::None,
};
// cbor encode the meta item
let cbor_encoded = meta_map.cbor_encode()?;
// decode the data back
let cbor_decoded_vec = RainMetaDocumentV1Item::cbor_decode(&cbor_encoded)?;
// unpack the payload into AuthoringMeta
let unpacked_payload: AuthoringMeta = cbor_decoded_vec[0].unpack_into()?;
Meta Storage (CAS)
Store
is a struct that provides functionalities to store, read, fetch(remotely) Rain metadata and ExpressionDeployers as a Content Addressed Storage(CAS), which is a critical piece of dotrain language server protocol and compiler implementation by caching all that is imported in .rain file that can be later accessed easily by language server and compiler.
use rain_meta::meta::Store;
use std::collections::HashMap;
// to instatiate with default rain subgraphs included
let mut store = Store::default();
// add a new subgraph endpoint url to the subgraph list
store.add_subgraphs(&vec!["subgraph-url"]);
// update the store with another Store (merges the stores)
store.merge(&Store::default());
// hash of a meta to search and store
let hash = "0x56ffc3fc82109c33f1e1544157a70144fc15e7c6e9ae9c65a636fd165b1bc51c";
// updates the meta store with a new meta by searching through subgraphs
store.update(&hash);
// searches for an deployer in the subgraphs and stores the result mapped to the hash
store.search_deployer(&hash);
// to get a record from store
let meta = store.get_meta(&hash);
// to get a ExpressionDeployer record from store
let deployer_record = store.get_deployer(&hash);
// path to a .rain file
let dotrain_uri = "path/to/file.rain";
// reading the dotrain content as an example,
// Store is agnostic to dotrain contents it just maps the hash of the content to the given
// uri and puts it as a new meta into the meta cache, so obtaining and passing the correct
// content is up to the implementer
let dotrain_content = std::fs::read_to_string(&dotrain_uri);
// updates the dotrain cache for a dotrain text and uri
let (new_hash, old_hash) = store.set_dotrain(&dotrain_content, &dotrain_uri, false)?;
// to get dotrain meta bytes given a uri
let dotrain_meta_bytes = store.get_dotrain_meta(&dotrain_uri);
Developers
To build from source first clone this repo and make sure you already have rustup
installed and next you can build the lib/binary using cargo build
, if you have nixOS installed you can simply run:
nix build
to build the binary crate or enter the nix with:
nix develop
which will fetch all the required packages and put them in your path and you can proceed to build lib/binary crate using cargo build
.
for running test use cargo test
and for generating docs use cargo doc
.
Dependencies
~14–28MB
~466K SLoC