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