Skip to main content

relate_core/
lib.rs

1//! Core values, errors, and identifiers for Relate.
2
3/// The byte bound of one wire message every surface frames around — the
4/// value Bolt's chunked framing caps a message at and the C ABI's params
5/// builder caps one `put_string` value at (single-sourced so the two
6/// surfaces can never disagree). Fixed constant, no knob (ADR-0514).
7pub const MAX_WIRE_MESSAGE_BYTES: usize = 16 * 1024 * 1024;
8
9mod arity;
10mod auto_literal;
11mod cancel;
12pub mod ce_messages;
13mod convert;
14mod dynamic;
15mod error;
16/// The shared error-kind vocabulary (ADR-0502 §2 moved it here from
17/// `relate-error`, which re-exports it): the finest TCK-aligned
18/// [`ErrorKind`], the eight [`TckErrorClass`]es, and the two detail
19/// helpers both error channels render through.
20mod error_kinds;
21pub mod file_identity;
22pub mod integer_args;
23mod memory_limit;
24mod namespace;
25mod output_safety;
26mod presence_bits;
27mod preview;
28pub mod temporal;
29pub mod tokens;
30mod traversal;
31mod typename;
32mod value;
33
34pub use arity::{
35    builtin_arity, ArityContract, CHAR_LENGTH_ARITY, FORMAT_ARITY,
36    FORMAT_REQUIRES_ONE_OR_TWO_ARGUMENTS, FUNCTION_REQUIRES_ONE_ARGUMENT, LENGTH_REQUIRES_A_PATH,
37    NULLIF_ARITY, NULLIF_REQUIRES_TWO_ARGUMENTS, VECTOR_ARITY, VECTOR_REQUIRES_THREE_ARGUMENTS,
38};
39pub use auto_literal::{auto_literal, AutoLiteralGuard};
40pub use cancel::CancelToken;
41pub use convert::{column_type_name, cypher_to_value, value_to_cypher};
42pub use dynamic::{
43    dynamic_label_names, dynamic_property_key, DynamicAccessError, DynamicNameToken,
44};
45pub use error::{
46    expected_type_detail, negative_page_bound_text, uniqueness_violation_detail, ArithmeticFailure,
47    CapacityKind, Error, Result, NEGATIVE_PAGE_BOUND_DETAIL,
48};
49pub use error_kinds::{
50    duplicate_variable_detail, undefined_variable_detail, unknown_function_detail, ErrorKind,
51    TckErrorClass,
52};
53pub use memory_limit::{
54    parse_expression_memory_limit, parse_memory_limit, parse_positive_memory_limit,
55    require_positive_memory_limit,
56};
57pub use namespace::{
58    is_graph_selector_function_name, node_element_id, parse_node_element_id, parse_rel_element_id,
59    rel_element_id, ElementIdRef, Namespace, GRAPH_SELECTOR_FUNCTIONS,
60    GRAPH_SELECTOR_FUNCTION_NAMES,
61};
62pub use output_safety::is_unsafe_output_char;
63pub use presence_bits::PresenceBits;
64pub use preview::{
65    preview_feature_disabled_text, PreviewFeature, PreviewFeatures, PREVIEW_FEATURES,
66};
67pub use temporal::{QueryClockGuard, Temporal};
68pub use tokens::{ExecutionReceipt, TokenEstimate, TokenOutcome};
69pub use traversal::{
70    require_traversal_depth, traversal_depth_exceeded_message, MAX_TRAVERSAL_DEPTH,
71    MAX_TRAVERSAL_DEPTH_CEILING,
72};
73pub use typename::{bare_type_name, expected_value_type_detail, value_type_name};
74pub use value::{
75    bytes_logical_bytes, logical_bytes_within, next_depth, point_component, str_logical_bytes,
76    tagged_str, uuid_hyphenated, uuid_parse, value_depth_exceeded, Node, Path, PointValue,
77    PropertyMap, Relationship, TaggedStr, Value, VectorCoordKind, MAX_VALUE_DEPTH,
78};
79
80pub type NodeId = i64;
81pub type RelId = i64;
82
83/// Whether `id` belongs to a CIP-257 **virtual** entity — a graph-type
84/// projection synthesized with a negative id and carried by its value alone
85/// (it has no store entry). Persisted ids are non-negative
86/// ([`validate_persisted_id`]), so the sign is the one virtual-entity test.
87pub const fn is_virtual_id(id: i64) -> bool {
88    id < 0
89}
90
91/// The single acceptance rule for a persisted local node or relationship ID.
92///
93/// The bound `0..i64::MAX` rejects a negative ID before it can seed a
94/// next-write counter and reserves `i64::MAX` as the unsupported sentinel,
95/// because installing a row advances the ID allocator. `what` labels the
96/// caller's context in the returned storage error. See ADR-0096.
97pub fn validate_persisted_id(id: i64, what: &str) -> Result<()> {
98    if id < 0 || id == i64::MAX {
99        return Err(Error::storage(format!(
100            "{what} ID {id} is outside 0..i64::MAX"
101        )));
102    }
103    Ok(())
104}
105
106#[cfg(test)]
107mod tests {
108    use super::*;
109
110    #[test]
111    fn persisted_id_predicate_accepts_in_range_and_rejects_zero_nine_six() {
112        for id in [0, 1, 42, i64::MAX - 1] {
113            validate_persisted_id(id, "node").unwrap();
114        }
115        for id in [-1, i64::MIN, i64::MAX] {
116            let error = validate_persisted_id(id, "node").unwrap_err();
117            assert!(matches!(error, Error::Storage(_)), "{error}");
118            assert_eq!(
119                error.to_string(),
120                format!("storage error: node ID {id} is outside 0..i64::MAX")
121            );
122        }
123    }
124}