Expand description
§vynil-core
Generic Rust toolbox combining a Rhai scripting engine and a Handlebars templating engine, with optional Kubernetes / OCI / S3 / HTTP handlers.
Extracted from the vynil workspace so it can be reused
by other projects (kuberest, kydah, …) without pulling in vynil’s business abstractions
(CRDs, package model, instance controllers).
Status: API is not yet stable — expect breaking changes before
1.0.
§Features
| Feature | Default | What it adds |
|---|---|---|
rhai | ✅ | engine::Script engine + every other module’s Rhai bindings |
hbs | ✅ | hbs::HandleBars engine |
hbs-scripting | ✅ | register_helper_dir / rhai_register_helper_dir (handlebars/script_helper). Implies hbs + rhai. Keep it separate because script_helper pulls smartstring which breaks String + &String in some graphs (see hbs docs) |
http | ✅ | http::RestClient (reqwest) + http_mock::RestClientMock. Implies rhai |
crypto | ✅ | argon_hash / bcrypt_hash / gen_private_key helpers (Handlebars). In Rhai: the Argon type via new_argon with its .hash method, plus bcrypt_hash / gen_private_key |
k8s | ❌ | Generic K8s handlers (k8s::K8sGeneric, k8s::K8sObject, …) + mocks. Implies rhai |
oci | ❌ | oci::Registry + OCI mock. Implies rhai |
s3 | ❌ | S3 helpers (s3::s3_get_yaml, s3::s3_list_keys). Implies rhai |
fs | ❌ | Filesystem access from Rhai (file_read, file_write, …) |
shell | ❌ | Shell execution (shell::run / shell::get_out + Rhai shell_run / shell_output); unix-only, commands are interpreted by a literal sh -c |
quantity | ❌ | Kubernetes Quantity parser (quantity::cpu_millis_of, quantity::memory_bytes_of), exact arithmetic; its Rhai glue needs rhai too |
password | ❌ | Auto-wires gen_password / gen_password_alphanum into new_bare and registers the Handlebars helpers; the Rhai glue itself compiles under rhai alone (opt-in to avoid name collisions) |
metadata | ❌ | Rhai introspection metadata: /// comments + parameter names on registered script functions, consumed by gen_fn_signatures / gen_fn_metadata_to_json. Implies rhai |
rt | ❌ | async → sync bridge rt::block_on for consumers; pulls tokio; does not imply rhai |
# default: Rhai + Handlebars + HTTP + crypto
vynil-core = "0.9"
# Kubernetes project
vynil-core = { version = "0.9", features = ["k8s"] }
# Handlebars only, no Rhai/smartstring in the graph
vynil-core = { version = "0.9", default-features = false, features = ["hbs", "crypto"] }§Quick start
vynil_core::set_client_name(|| "my-app.example.com".to_string());
// Rhai
let mut script = vynil_core::engine::Script::new_bare(vec!["scripts/".into()]);
script.engine.register_fn("my_fn", |s: String| s.len() as i64);
// script.run_file(&std::path::PathBuf::from("scripts/run.rhai"))?;
// Handlebars
let mut hbs = vynil_core::hbs::HandleBars::new();
let out = hbs.render("Hello {{ name }}!", &serde_json::json!({"name": "world"})).unwrap();
assert_eq!(out, "Hello world!");§Client identity
vynil-core does not assume an identity. Call set_client_name once at startup
before any HTTP or Kubernetes call, otherwise those calls panic with an actionable message.
vynil_core::set_client_name(|| "my-app.example.com".to_string());
assert!(vynil_core::client_name_is_set());§Rhai helpers (injected by engine::Script::new_bare)
Common: sha256, log_debug/info/warn/error, url_encode, get_env, to_decimal,
base64_encode/decode, json_encode/decode, basename, dirname.
Also available under rhai alone, no extra feature: yaml_encode/decode,
semver_from + inc_*, glob, date_now/format, crc32_hash.
Feature-gated: Argon (new_argon + .hash) / bcrypt_hash / gen_private_key
(feature crypto), gen_password (feature password), file_* (feature fs),
shell_* (feature shell), and Registry (feature oci).
Never injected by new_bare, even with every feature enabled: s3_*, RestClient
and k8s_* are registered only on the caller’s consent — s3_rhai_register,
http_rhai_register and the k8s_rhai_register registrar.
Scripts also get assert and import_run / import_template shims for optional imports.
§Handlebars helpers (injected by hbs::HandleBars::new)
See hbs::CORE_HBS_HELPERS for the full list. Highlights: base64_encode/decode,
url_encode, to_decimal, header_basic, crc32_hash, argon_hash/bcrypt_hash/gen_private_key
(feature crypto), gen_password* (feature password), plus the handlebars_misc_helpers
set and the vendored json_to_str / str_to_json / json_query family.
§Crate boundaries
This crate stays generic: no dependency on vynil, kuberest or kydah, no default
client name, no CRDs or vynil-specific Handlebars helpers.
Re-exports§
pub use client_name::client_name_is_set;pub use client_name::get_client_name;pub use client_name::set_client_name;pub use semver::Semver;pub use engine::Script;rhaipub use hbs::HandleBars;hbspub use k8s::update_cache;k8s
Modules§
- cancel
- Cooperative cancellation of blocking native calls (
CancelToken+ thread-scopedscope). Compiled without any feature: the token is read byrt::block_onand bysleep(rhai). Cooperative cancellation of the crate’s blocking native calls (sleepinengine,rt::block_on) for a consumer driving a Rhai script (typically an LLM session). - chrono
- Date/time helpers (
DateTimeHandler). Date/time helper for Rhai. - client_
name - Global client identity (
User-Agent/ field-manager). Global client identity used as HTTPUser-Agentand Kubernetes field-manager. - engine
rhai - Rhai scripting engine (
engine::Script) and its registered helpers. Rhai scripting engine. - glob
rhai - Glob matching (
globRhai helper). - hashes
- Hash helpers (crc32, bcrypt, argon2).
Hash helpers:
crc32_hash(always),bcrypt_hash/Argon(featurecrypto). - hbs
hbs - Handlebars templating engine (
hbs::HandleBars) and its helpers. Handlebars templating engine. - http
http - HTTP client (
http::RestClient). HTTP client (RestClient) and free helpers (http_get_yaml,headers_get). - http_
mock http - Mock HTTP client for tests (
http_mock::RestClientMock). Mock HTTP client for tests — Rhai-compatible drop-in forcrate::http::RestClient. - k8s
k8s - Kubernetes handlers (
K8sGeneric,K8sObject, …). Kubernetes handlers. - k8s_
mock k8s - Mock Kubernetes helpers. Mock Kubernetes handlers for tests.
- key
crypto - Private key generation (RSA / ed25519 via OpenSSL). Private key generation (RSA / ed25519 via OpenSSL).
- oci
oci - OCI registry client (
oci::Registry). OCI registry helpers (Registry) and auth utilities. - oci_
mock oci - Mock OCI helpers.
Mock OCI registry for tests. See
crate::oci::Registryfor the real client. - password
- Password generation. Password generation with per-class minimums.
- quantity
quantity - Kubernetes
Quantityparsing (cpu_millis_of,memory_bytes_of), exact arithmetic. KubernetesQuantityparser (500m,2Gi,1.5e3…), exact integer arithmetic. - rt
rt - Async → sync bridge (
rt::block_on) for synchronous Rhai callers, shared by thehttp,oci,s3andk8smodules and public for consumers; only compiled with thertfeature. Async → sync bridge, shared by the network-facing modules (http,oci,s3,k8s), which expose synchronous functions to Rhai scripts while every network call underneath istokio-async, and public (featurert) for consumers doing the same. One bridge, one strategy table (seecrate::rt::block_on), no panic escaping towards the host. The module knows nothing of Rhai: callers convert the error themselves. - s3
s3 - S3 helpers (
s3_get_yaml,s3_list_keys). S3 helpers (s3_get_yaml,s3_list_keys) exposed to Rhai. - semver
- Semver parsing and mutation. Semver parsing and bumping.
- shell
shell - Shell execution helpers. Shell execution helpers.
- yaml
- YAML ↔ JSON helpers. YAML ↔ JSON / Rhai helpers.
Macros§
- register_
k8s_ generic k8s - Registers
$typeas the Rhai type"K8sGeneric": the threek8s_resourceconstructors ($new_global,$new_ns,$new_group_ns) plus CRUD/list/scope methods. Takes$obj_typeas the object type returned byget_obj. - register_
k8s_ object k8s - Registers
$typeas the Rhai type"K8sObject": kind/metadata getters plusdeleteand thewait_*methods. - register_
k8s_ raw k8s - Registers
$typeas the Rhai type"K8sRaw"with the$newconstructor and theget_url/get_cluster_version/get_api_resourcesmethods.
Enums§
- Error
- Errors returned by
vynil-coreoperations.
Functions§
- error_
chain - Render an error together with its full
source()chain, e.g.error sending request for url (...): dns error: failed to lookup address information: .... - rhai_
err rhai - Convert a
Errorinto a RhaiEvalAltResult, including its fullsource()chain (seeerror_chain) so the real cause of a connection-level failure isn’t swallowed. - rhai_
err_ str rhai - Convert a string into a Rhai
EvalAltResult.