Skip to main content

Crate vynil_core

Crate vynil_core 

Source
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

FeatureDefaultWhat 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;rhai
pub use hbs::HandleBars;hbs
pub use k8s::update_cache;k8s

Modules§

cancel
Cooperative cancellation of blocking native calls (CancelToken + thread-scoped scope). Compiled without any feature: the token is read by rt::block_on and by sleep (rhai). Cooperative cancellation of the crate’s blocking native calls (sleep in engine, 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 HTTP User-Agent and Kubernetes field-manager.
enginerhai
Rhai scripting engine (engine::Script) and its registered helpers. Rhai scripting engine.
globrhai
Glob matching (glob Rhai helper).
hashes
Hash helpers (crc32, bcrypt, argon2). Hash helpers: crc32_hash (always), bcrypt_hash / Argon (feature crypto).
hbshbs
Handlebars templating engine (hbs::HandleBars) and its helpers. Handlebars templating engine.
httphttp
HTTP client (http::RestClient). HTTP client (RestClient) and free helpers (http_get_yaml, headers_get).
http_mockhttp
Mock HTTP client for tests (http_mock::RestClientMock). Mock HTTP client for tests — Rhai-compatible drop-in for crate::http::RestClient.
k8sk8s
Kubernetes handlers (K8sGeneric, K8sObject, …). Kubernetes handlers.
k8s_mockk8s
Mock Kubernetes helpers. Mock Kubernetes handlers for tests.
keycrypto
Private key generation (RSA / ed25519 via OpenSSL). Private key generation (RSA / ed25519 via OpenSSL).
ocioci
OCI registry client (oci::Registry). OCI registry helpers (Registry) and auth utilities.
oci_mockoci
Mock OCI helpers. Mock OCI registry for tests. See crate::oci::Registry for the real client.
password
Password generation. Password generation with per-class minimums.
quantityquantity
Kubernetes Quantity parsing (cpu_millis_of, memory_bytes_of), exact arithmetic. Kubernetes Quantity parser (500m, 2Gi, 1.5e3…), exact integer arithmetic.
rtrt
Async → sync bridge (rt::block_on) for synchronous Rhai callers, shared by the http, oci, s3 and k8s modules and public for consumers; only compiled with the rt feature. 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 is tokio-async, and public (feature rt) for consumers doing the same. One bridge, one strategy table (see crate::rt::block_on), no panic escaping towards the host. The module knows nothing of Rhai: callers convert the error themselves.
s3s3
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.
shellshell
Shell execution helpers. Shell execution helpers.
yaml
YAML ↔ JSON helpers. YAML ↔ JSON / Rhai helpers.

Macros§

register_k8s_generick8s
Registers $type as the Rhai type "K8sGeneric": the three k8s_resource constructors ($new_global, $new_ns, $new_group_ns) plus CRUD/list/scope methods. Takes $obj_type as the object type returned by get_obj.
register_k8s_objectk8s
Registers $type as the Rhai type "K8sObject": kind/metadata getters plus delete and the wait_* methods.
register_k8s_rawk8s
Registers $type as the Rhai type "K8sRaw" with the $new constructor and the get_url / get_cluster_version / get_api_resources methods.

Enums§

Error
Errors returned by vynil-core operations.

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_errrhai
Convert a Error into a Rhai EvalAltResult, including its full source() chain (see error_chain) so the real cause of a connection-level failure isn’t swallowed.
rhai_err_strrhai
Convert a string into a Rhai EvalAltResult.

Type Aliases§

Result
Crate result type. E defaults to Error.
RhaiResrhai
Result type used by Rhai-exposed functions. Alias for Result<T, Box<EvalAltResult>>.