fraiseql_core/runtime/
relay.rs

1//! Relay cursor encoding and decoding.
2//!
3//! FraiseQL uses two kinds of cursors:
4//!
5//! ## Edge Cursor (keyset pagination)
6//!
7//! Used in `XxxConnection.edges[].cursor` for forward/backward pagination.
8//! Encodes the BIGINT primary key (`pk_{type}`) as `base64(pk_value_decimal_string)`.
9//!
10//! Example: `pk_user = 42` → cursor = `base64("42")` = `"NDI="`
11//!
12//! ## Node ID (global object identification)
13//!
14//! Used in the `Node.id` field and the `node(id: ID!)` global query.
15//! Encodes type name + UUID as `base64("TypeName:uuid")`.
16//!
17//! Example: User with UUID `"550e8400-..."` → `base64("User:550e8400-...")`.
18//!
19//! ## Relay spec references
20//!
21//! - [Global Object Identification](https://relay.dev/graphql/objectidentification.htm)
22//! - [Cursor Connections](https://relay.dev/graphql/connections.htm)
23
24use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64};
25
26/// Encode a BIGINT primary key value as a Relay edge cursor.
27///
28/// The cursor is `base64(pk_string)` where `pk_string` is the decimal
29/// representation of the BIGINT.  Base64 is encoding, not encryption —
30/// a client that decodes the cursor will see the raw integer PK value.
31/// The Relay spec requires cursors to be treated as opaque by convention,
32/// but provides no cryptographic guarantee.
33///
34/// # Example
35///
36/// ```
37/// use fraiseql_core::runtime::relay::encode_edge_cursor;
38///
39/// let cursor = encode_edge_cursor(42);
40/// assert_eq!(cursor, base64_of("42"));
41/// # fn base64_of(s: &str) -> String {
42/// #     use base64::{Engine as _, engine::general_purpose::STANDARD};
43/// #     STANDARD.encode(s)
44/// # }
45/// ```
46#[must_use]
47pub fn encode_edge_cursor(pk: i64) -> String {
48    BASE64.encode(pk.to_string())
49}
50
51/// Decode a Relay edge cursor back to a BIGINT primary key value.
52///
53/// Returns `None` if the cursor is not valid base64 or does not contain a
54/// valid decimal integer.
55///
56/// # Example
57///
58/// ```
59/// use fraiseql_core::runtime::relay::{decode_edge_cursor, encode_edge_cursor};
60///
61/// let cursor = encode_edge_cursor(42);
62/// assert_eq!(decode_edge_cursor(&cursor), Some(42));
63/// assert_eq!(decode_edge_cursor("not-valid-base64!!"), None);
64/// ```
65#[must_use]
66pub fn decode_edge_cursor(cursor: &str) -> Option<i64> {
67    let bytes = BASE64.decode(cursor).ok()?;
68    let s = std::str::from_utf8(&bytes).ok()?;
69    s.parse::<i64>().ok()
70}
71
72/// Encode a UUID string as a Relay edge cursor.
73///
74/// The cursor is `base64(uuid_string)`.  Base64 is encoding, not encryption —
75/// a client that decodes the cursor will see the raw UUID.  The Relay spec
76/// requires cursors to be treated as opaque by convention, but provides no
77/// cryptographic guarantee.
78///
79/// # Example
80///
81/// ```
82/// use fraiseql_core::runtime::relay::{decode_uuid_cursor, encode_uuid_cursor};
83///
84/// let uuid = "550e8400-e29b-41d4-a716-446655440000";
85/// let cursor = encode_uuid_cursor(uuid);
86/// assert_eq!(decode_uuid_cursor(&cursor), Some(uuid.to_string()));
87/// ```
88#[must_use]
89pub fn encode_uuid_cursor(uuid: &str) -> String {
90    BASE64.encode(uuid)
91}
92
93/// Decode a Relay edge cursor back to a UUID string.
94///
95/// Returns `None` if the cursor is not valid base64 or not valid UTF-8.
96///
97/// # Example
98///
99/// ```
100/// use fraiseql_core::runtime::relay::{decode_uuid_cursor, encode_uuid_cursor};
101///
102/// let uuid = "550e8400-e29b-41d4-a716-446655440000";
103/// let cursor = encode_uuid_cursor(uuid);
104/// assert_eq!(decode_uuid_cursor(&cursor), Some(uuid.to_string()));
105/// assert_eq!(decode_uuid_cursor("not-valid-base64!!"), None);
106/// ```
107#[must_use]
108pub fn decode_uuid_cursor(cursor: &str) -> Option<String> {
109    let bytes = BASE64.decode(cursor).ok()?;
110    std::str::from_utf8(&bytes).ok().map(str::to_owned)
111}
112
113/// Encode a global Node ID as a Relay-compatible ID.
114///
115/// The format is `base64("TypeName:uuid")`.  Base64 is encoding, not
116/// encryption — a client that decodes the ID will see the type name and UUID.
117///
118/// # Example
119///
120/// ```
121/// use fraiseql_core::runtime::relay::encode_node_id;
122///
123/// let id = encode_node_id("User", "550e8400-e29b-41d4-a716-446655440000");
124/// // id = base64("User:550e8400-e29b-41d4-a716-446655440000")
125/// assert!(!id.is_empty());
126/// ```
127#[must_use]
128pub fn encode_node_id(type_name: &str, uuid: &str) -> String {
129    BASE64.encode(format!("{type_name}:{uuid}"))
130}
131
132/// Decode a Relay global Node ID back to `(type_name, uuid)`.
133///
134/// Returns `None` if the ID is not valid base64 or does not have the
135/// expected `"TypeName:uuid"` format.
136///
137/// # Example
138///
139/// ```
140/// use fraiseql_core::runtime::relay::{decode_node_id, encode_node_id};
141///
142/// let id = encode_node_id("User", "550e8400-e29b-41d4-a716-446655440000");
143/// let decoded = decode_node_id(&id);
144/// assert_eq!(
145///     decoded,
146///     Some(("User".to_string(), "550e8400-e29b-41d4-a716-446655440000".to_string()))
147/// );
148/// ```
149#[must_use]
150pub fn decode_node_id(id: &str) -> Option<(String, String)> {
151    let bytes = BASE64.decode(id).ok()?;
152    let s = std::str::from_utf8(&bytes).ok()?;
153    let (type_name, uuid) = s.split_once(':')?;
154    if type_name.is_empty() || uuid.is_empty() {
155        return None;
156    }
157    Some((type_name.to_string(), uuid.to_string()))
158}
fraiseql_core/runtime/relay.rs

fraiseql_core/runtime/
relay.rs
