Git-Mirrors/veilid
1
0
Fork 0
mirror of https://gitlab.com/veilid/veilid.git synced 2025-08-03 04:06:11 -04:00
Code Issues Projects Releases Packages Wiki Activity

Add READMEs, basic veilid-core example

Browse source
This commit is contained in:
Brandon Vandegrift 2025-05-30 18:51:29 -04:00
parent 17f48870b6
commit 8c817655e8
16 changed files with 161 additions and 58 deletions
Download patch file Download diff file Expand all files Collapse all files

8
Cargo.lock generated
View file

@ -6530,6 +6530,14 @@ dependencies = [
"x25519-dalek",
]
[[package]]
name = "veilid-core-examples-basic"
version = "0.1.0"
dependencies = [
"tokio",
"veilid-core",
]
[[package]]
name = "veilid-flutter"
version = "0.4.6"

1
Cargo.toml
View file

@ -2,6 +2,7 @@
members = [
"veilid-tools",
"veilid-core",
"veilid-core/examples/basic",
"veilid-server",
"veilid-cli",
"veilid-flutter/rust",

56
README.md
View file

@ -18,61 +18,9 @@ The easiest way to help grow the Veilid network is to run your own node. Every u
To run such a node, establish a Debian or Fedora based VPS and install the veilid-server service. To make this process simple we are hosting package manager repositories for .deb and .rpm packages. See the [installing](./INSTALL.md) guide for more information.
## Building on Veilid
## Building with Veilid
If you want to start using Veilid for your own app, take a look at the [Developer Book](https://veilid.gitlab.io/developer-book/).
A basic example using `veilid-core` and `tokio` might look like this.
```rust
use std::sync::Arc;
use veilid_core::VeilidUpdate::{AppMessage, Network};
use veilid_core::{VeilidConfigBlockStore, VeilidConfig, VeilidConfigProtectedStore, VeilidConfigTableStore, VeilidUpdate};
#[tokio::main]
async fn main() {
let update_callback = Arc::new(move |update: VeilidUpdate| {
match update {
AppMessage(msg) => {
println!("Message: {}", String::from_utf8_lossy(msg.message().into()));
}
Network(msg) => {
println!("Network: Peers {:}, bytes/sec [{} up] [{} down]", msg.peers.iter().count(), msg.bps_up, msg.bps_down)
}
_ => {
println!("{:?}", update)
}
};
});
let config = VeilidConfig {
program_name: "Example Veilid".into(),
namespace: "veilid-example".into(),
protected_store: VeilidConfigProtectedStore {
// avoid prompting for password, don't do this in production
always_use_insecure_storage: true,
directory: "./.veilid/block_store".into(),
..Default::default()
},
block_store: VeilidConfigBlockStore {
directory: "./.veilid/block_store".into(),
..Default::default()
},
table_store: VeilidConfigTableStore {
directory: "./.veilid/table_store".into(),
..Default::default()
},
..Default::default()
};
let veilid = veilid_core::api_startup_config(update_callback, config).await.unwrap();
println!("Node ID: {}", veilid.config().unwrap().get().network.routing_table.node_id);
veilid.attach().await.unwrap();
// Until CTRL+C is pressed, keep running
tokio::signal::ctrl_c().await.unwrap();
veilid.shutdown().await;
}
```
See the [README for veilid-core](./veilid-core/README.md)
## Development

1
veilid-cli/Cargo.toml
View file

@ -10,6 +10,7 @@ authors.workspace = true
license.workspace = true
edition.workspace = true
rust-version.workspace = true
publish = false
[[bin]]
name = "veilid-cli"

2
veilid-core/Cargo.toml
View file

@ -11,6 +11,8 @@ authors.workspace = true
license.workspace = true
edition.workspace = true
rust-version.workspace = true
documentation = "https://docs.rs/veilid-core"
homepage = "https://veilid.gitlab.io/developer-book/"
[lib]
crate-type = ["cdylib", "staticlib", "rlib"]

34
veilid-core/README.md Normal file
View file

@ -0,0 +1,34 @@
<!-- DO NOT EDIT BELOW - content within cargo-sync-readme blocks is generated -->
<!-- cargo-sync-readme start -->
# The Veilid Framework
This is the core library used to create a Veilid node and operate it as part of an application.
`veilid-core` contains all of the core logic for Veilid and can be used in mobile applications as well as desktop
and in-browser WebAssembly apps.
## Getting started
- [Developer Book](https://veilid.gitlab.io/developer-book/)
- [Examples](https://gitlab.com/veilid/veilid/-/tree/main/veilid-core/examples/)
- [API Documentation](https://docs.rs/veilid-core)
The public API is accessed by getting a [VeilidAPI] object via a call to [api_startup], [api_startup_json], or
[api_startup_config].
From there, a [RoutingContext] object can get you access to public and private routed operations.
## Cargo features
The default `veilid-core` configurations are:
* `default` - Uses `tokio` as the async runtime.
If you use `--no-default-features`, you can switch to other runtimes:
* `default-async-std` - Uses `async-std` as the async runtime.
* `default-wasm` - When building for the `wasm32` architecture, use this to enable `wasm-bindgen-futures` as the async runtime.
<!-- cargo-sync-readme end -->

1
veilid-core/examples/basic/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
.veilid

16
veilid-core/examples/basic/Cargo.toml Normal file
View file

@ -0,0 +1,16 @@
[package]
name = "veilid-core-examples-basic"
version = "0.1.0"
repository.workspace = true
authors.workspace = true
license.workspace = true
edition.workspace = true
rust-version.workspace = true
publish = false
[dependencies]
tokio = { version = "^1.43.0" }
veilid-core = { version = "0.4.6", path = "../../../veilid-core" }
[lints]
workspace = true

55
veilid-core/examples/basic/src/main.rs Normal file
View file

@ -0,0 +1,55 @@
use std::sync::Arc;
use veilid_core::VeilidUpdate::{AppMessage, Network};
use veilid_core::{VeilidConfig, VeilidConfigProtectedStore, VeilidConfigTableStore, VeilidUpdate};
#[tokio::main]
async fn main() {
let update_callback = Arc::new(move |update: VeilidUpdate| {
match update {
AppMessage(msg) => {
println!("Message: {}", String::from_utf8_lossy(msg.message()));
}
Network(msg) => {
println!(
"Network: Peers {:}, bytes/sec [{} up] [{} down]",
msg.peers.len(),
msg.bps_up,
msg.bps_down
)
}
_ => {
println!("{:#?}", update)
}
};
});
let config = VeilidConfig {
program_name: "Example Veilid".into(),
namespace: "veilid-example".into(),
protected_store: VeilidConfigProtectedStore {
// IMPORTANT: don't do this in production
// This avoids prompting for a password and is insecure
always_use_insecure_storage: true,
directory: "./.veilid/protected_store".into(),
..Default::default()
},
table_store: VeilidConfigTableStore {
directory: "./.veilid/table_store".into(),
..Default::default()
},
..Default::default()
};
let veilid = veilid_core::api_startup_config(update_callback, config)
.await
.unwrap();
println!(
"Node ID: {}",
veilid.config().unwrap().get().network.routing_table.node_id
);
veilid.attach().await.unwrap();
// Until CTRL+C is pressed, keep running
tokio::signal::ctrl_c().await.unwrap();
veilid.shutdown().await;
}

10
veilid-core/src/lib.rs
View file

@ -1,16 +1,22 @@
//! # The Veilid Framework
//!
//! Core library used to create a Veilid node and operate it as part of an application.
//! This is the core library used to create a Veilid node and operate it as part of an application.
//!
//! `veilid-core` contains all of the core logic for Veilid and can be used in mobile applications as well as desktop
//! and in-browser WebAssembly apps.
//!
//! ## Getting started
//!
//! - [Developer Book](https://veilid.gitlab.io/developer-book/)
//! - [Examples](https://gitlab.com/veilid/veilid/-/tree/main/veilid-core/examples/)
//! - [API Documentation](https://docs.rs/veilid-core)
//!
//! The public API is accessed by getting a [VeilidAPI] object via a call to [api_startup], [api_startup_json], or
//! [api_startup_config].
//!
//! From there, a [RoutingContext] object can get you access to public and private routed operations.
//!
//! ## Features
//! ## Cargo features
//!
//! The default `veilid-core` configurations are:
//!

1
veilid-flutter/rust/Cargo.toml
View file

@ -10,6 +10,7 @@ authors.workspace = true
license.workspace = true
edition.workspace = true
rust-version.workspace = true
publish = false
[lib]
crate-type = ["cdylib", "staticlib", "rlib"]

1
veilid-server/Cargo.toml
View file

@ -10,6 +10,7 @@ authors.workspace = true
license.workspace = true
edition.workspace = true
rust-version.workspace = true
publish = false
[[bin]]
name = "veilid-server"

2
veilid-tools/Cargo.toml
View file

@ -10,6 +10,8 @@ authors.workspace = true
license.workspace = true
edition.workspace = true
rust-version.workspace = true
documentation = "https://docs.rs/veilid-tools"
homepage = "https://veilid.gitlab.io/developer-book/"
[lib]
# staticlib for iOS tests, cydlib for android tests, rlib for everything else

26
veilid-tools/README.md Normal file
View file

@ -0,0 +1,26 @@
<!-- DO NOT EDIT BELOW - content within cargo-sync-readme blocks is generated -->
<!-- cargo-sync-readme start -->
# veilid-tools
A collection of baseline tools for Rust development use by Veilid and Veilid-enabled Rust applications
These are used by `veilid-core`, `veilid-server`, `veilid-cli` and may be used by any other applications
that link in `veilid-core` if a common baseline of functionality is desired. Extending this crate with new
utility functions is encouraged rather than adding 'common' functionality to `veilid-core`, allowing it to
remain free of boilerplate and utility classes that could be reused elsewhere.
Everything added to this crate must be extensively unit-tested.
## Cargo features
The default `veilid-tools` configurations are:
- `default` - Uses `tokio` as the async runtime
If you use `--no-default-features`, you can switch to other runtimes:
- `rt-async-std` - Uses `async-std` as the async runtime
- `rt-wasm-bindgen` - When building for the `wasm32` architecture, use this to enable `wasm-bindgen-futures` as the async runtime
<!-- cargo-sync-readme end -->

4
veilid-tools/src/lib.rs
View file

@ -1,4 +1,4 @@
//! # Veilid Tools
//! # veilid-tools
//!
//! A collection of baseline tools for Rust development use by Veilid and Veilid-enabled Rust applications
//!
@ -9,7 +9,7 @@
//!
//! Everything added to this crate must be extensively unit-tested.
//!
//! ## Features
//! ## Cargo features
//!
//! The default `veilid-tools` configurations are:
//!

1
veilid-wasm/Cargo.toml
View file

@ -10,6 +10,7 @@ authors.workspace = true
license.workspace = true
edition.workspace = true
rust-version.workspace = true
publish = false
[lib]
crate-type = ["cdylib", "rlib"]