pub struct Name { /* private fields */ }Expand description
A nonempty, namespace-aware canonical runtime tool name.
The namespace is syntax only. Core owns the grammar — an optional
namespace component, one reserved / separator, both components non-empty —
and the canonical spelling used as the collision and routing key. It assigns
no meaning to any namespace value, reserves none, and derives no behaviour
from one; deciding what a namespace stands for is composition-layer policy.
Namespacing creates no resolution order: a/x and x are different
canonical names and never collide, while two registrations of a/x collide
regardless of which source produced each.
Name::to_wire and Name::parse_canonical are inverses, so a
composition layer that aggregates several tool sources can recover core’s
exact collision key from an advertised spelling instead of re-implementing
the split.
use reef_core::runtime::tool;
let scoped = tool::Name::namespaced("server".to_owned(), "search".to_owned()).unwrap();
let wire = scoped.to_wire();
assert_eq!(wire.as_str(), "server/search");
assert_eq!(tool::Name::parse_canonical(wire.as_str()).unwrap(), scoped);
// A namespaced name never collides with the bare local spelling.
let plain = tool::Name::parse_canonical("search").unwrap();
assert_eq!(plain.namespace(), None);
assert_ne!(plain, scoped);Implementations§
Source§impl Name
impl Name
Sourcepub fn local(local: String) -> Result<Self, NameError>
pub fn local(local: String) -> Result<Self, NameError>
Creates an unnamespaced tool name.
§Errors
NameError::EmptyLocal if local has no characters, or
NameError::ReservedSeparator if it contains /. The separator is
refused rather than escaped because it is the collision key’s only
structure: a local name carrying one would be indistinguishable from a
namespaced name built by Name::namespaced.
Sourcepub fn namespaced(namespace: String, local: String) -> Result<Self, NameError>
pub fn namespaced(namespace: String, local: String) -> Result<Self, NameError>
Creates a namespaced tool name.
§Errors
NameError::EmptyLocal for an empty local,
NameError::EmptyNamespace for an empty namespace — which would spell
the same canonical name as an unnamespaced one while claiming to be
scoped — or NameError::ReservedSeparator if either component contains
/. Nothing here validates what the namespace means: core owns the
grammar and reserves no value.
Sourcepub fn parse_canonical(canonical: &str) -> Result<Self, NameError>
pub fn parse_canonical(canonical: &str) -> Result<Self, NameError>
Splits a canonical spelling back into its validated components.
This is the exact inverse of Name::canonical and Name::to_wire:
the spelling is split at its first reserved separator and the components
are validated by the same rules Name::local and Name::namespaced
apply, so no caller has to reproduce the split to obtain core’s collision
key.
§Errors
Returns NameError::EmptyLocal for an empty spelling or one ending in
the separator, NameError::EmptyNamespace for one beginning with it,
and NameError::ReservedSeparator for a spelling carrying more than
one.
Sourcepub fn local_name(&self) -> &str
pub fn local_name(&self) -> &str
Returns the nonempty local component.
Sourcepub fn canonical(&self) -> &str
pub fn canonical(&self) -> &str
Returns the stable canonical spelling used for collision and routing.
Sourcepub fn to_wire(&self) -> Name
pub fn to_wire(&self) -> Name
Renders the uninterpreted wire spelling advertised to a model.
The result is a crate::value::tool_call::Name, the open leaf value a
model emission also arrives as, which is what makes the advertise/route
round trip typed on both sides.