Line data Source code
1 : use std::num::ParseIntError;
2 : use std::{fmt, str::FromStr};
3 :
4 : use anyhow::Context;
5 : use hex::FromHex;
6 : use rand::Rng;
7 : use serde::de::Visitor;
8 : use serde::{Deserialize, Serialize};
9 : use thiserror::Error;
10 :
11 0 : #[derive(Error, Debug)]
12 : pub enum IdError {
13 : #[error("invalid id length {0}")]
14 : SliceParseError(usize),
15 : }
16 :
17 : /// Neon ID is a 128-bit random ID.
18 : /// Used to represent various identifiers. Provides handy utility methods and impls.
19 : ///
20 : /// NOTE: It (de)serializes as an array of hex bytes, so the string representation would look
21 : /// like `[173,80,132,115,129,226,72,254,170,201,135,108,199,26,228,24]`.
22 : #[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
23 : struct Id([u8; 16]);
24 :
25 : impl Serialize for Id {
26 13614 : fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
27 13614 : where
28 13614 : S: serde::Serializer,
29 13614 : {
30 13614 : if serializer.is_human_readable() {
31 3261 : serializer.collect_str(self)
32 : } else {
33 10353 : self.0.serialize(serializer)
34 : }
35 13614 : }
36 : }
37 :
38 : impl<'de> Deserialize<'de> for Id {
39 164534 : fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
40 164534 : where
41 164534 : D: serde::Deserializer<'de>,
42 164534 : {
43 : struct IdVisitor {
44 : is_human_readable_deserializer: bool,
45 : }
46 :
47 : impl<'de> Visitor<'de> for IdVisitor {
48 : type Value = Id;
49 :
50 0 : fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
51 0 : if self.is_human_readable_deserializer {
52 0 : formatter.write_str("value in form of hex string")
53 : } else {
54 0 : formatter.write_str("value in form of integer array([u8; 16])")
55 : }
56 0 : }
57 :
58 164032 : fn visit_seq<A>(self, seq: A) -> Result<Self::Value, A::Error>
59 164032 : where
60 164032 : A: serde::de::SeqAccess<'de>,
61 164032 : {
62 164032 : let s = serde::de::value::SeqAccessDeserializer::new(seq);
63 164032 : let id: [u8; 16] = Deserialize::deserialize(s)?;
64 164032 : Ok(Id::from(id))
65 164032 : }
66 :
67 502 : fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
68 502 : where
69 502 : E: serde::de::Error,
70 502 : {
71 502 : Id::from_str(v).map_err(E::custom)
72 502 : }
73 : }
74 :
75 164534 : if deserializer.is_human_readable() {
76 502 : deserializer.deserialize_str(IdVisitor {
77 502 : is_human_readable_deserializer: true,
78 502 : })
79 : } else {
80 164032 : deserializer.deserialize_tuple(
81 164032 : 16,
82 164032 : IdVisitor {
83 164032 : is_human_readable_deserializer: false,
84 164032 : },
85 164032 : )
86 : }
87 164534 : }
88 : }
89 :
90 : impl Id {
91 14 : pub fn from_slice(src: &[u8]) -> Result<Id, IdError> {
92 14 : if src.len() != 16 {
93 0 : return Err(IdError::SliceParseError(src.len()));
94 14 : }
95 14 : let mut id_array = [0u8; 16];
96 14 : id_array.copy_from_slice(src);
97 14 : Ok(id_array.into())
98 14 : }
99 :
100 11 : pub fn as_arr(&self) -> [u8; 16] {
101 11 : self.0
102 11 : }
103 :
104 5559 : pub fn generate() -> Self {
105 5559 : let mut tli_buf = [0u8; 16];
106 5559 : rand::thread_rng().fill(&mut tli_buf);
107 5559 : Id::from(tli_buf)
108 5559 : }
109 :
110 217877 : fn hex_encode(&self) -> String {
111 : static HEX: &[u8] = b"0123456789abcdef";
112 :
113 217877 : let mut buf = vec![0u8; self.0.len() * 2];
114 3486032 : for (&b, chunk) in self.0.as_ref().iter().zip(buf.chunks_exact_mut(2)) {
115 3486032 : chunk[0] = HEX[((b >> 4) & 0xf) as usize];
116 3486032 : chunk[1] = HEX[(b & 0xf) as usize];
117 3486032 : }
118 :
119 : // SAFETY: vec constructed out of `HEX`, it can only be ascii
120 217877 : unsafe { String::from_utf8_unchecked(buf) }
121 217877 : }
122 : }
123 :
124 : impl FromStr for Id {
125 : type Err = hex::FromHexError;
126 :
127 15555 : fn from_str(s: &str) -> Result<Id, Self::Err> {
128 15555 : Self::from_hex(s)
129 15555 : }
130 : }
131 :
132 : // this is needed for pretty serialization and deserialization of Id's using serde integration with hex crate
133 : impl FromHex for Id {
134 : type Error = hex::FromHexError;
135 :
136 15663 : fn from_hex<T: AsRef<[u8]>>(hex: T) -> Result<Self, Self::Error> {
137 15663 : let mut buf: [u8; 16] = [0u8; 16];
138 15663 : hex::decode_to_slice(hex, &mut buf)?;
139 15654 : Ok(Id(buf))
140 15663 : }
141 : }
142 :
143 : impl AsRef<[u8]> for Id {
144 0 : fn as_ref(&self) -> &[u8] {
145 0 : &self.0
146 0 : }
147 : }
148 :
149 : impl From<[u8; 16]> for Id {
150 440156 : fn from(b: [u8; 16]) -> Self {
151 440156 : Id(b)
152 440156 : }
153 : }
154 :
155 : impl From<Id> for u128 {
156 0 : fn from(id: Id) -> Self {
157 0 : u128::from_le_bytes(id.0)
158 0 : }
159 : }
160 :
161 : impl fmt::Display for Id {
162 207889 : fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
163 207889 : f.write_str(&self.hex_encode())
164 207889 : }
165 : }
166 :
167 : impl fmt::Debug for Id {
168 9988 : fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
169 9988 : f.write_str(&self.hex_encode())
170 9988 : }
171 : }
172 :
173 : macro_rules! id_newtype {
174 : ($t:ident) => {
175 : impl $t {
176 14 : pub fn from_slice(src: &[u8]) -> Result<$t, IdError> {
177 14 : Ok($t(Id::from_slice(src)?))
178 14 : }
179 :
180 11 : pub fn as_arr(&self) -> [u8; 16] {
181 11 : self.0.as_arr()
182 11 : }
183 :
184 5559 : pub fn generate() -> Self {
185 5559 : $t(Id::generate())
186 5559 : }
187 :
188 24 : pub const fn from_array(b: [u8; 16]) -> Self {
189 24 : $t(Id(b))
190 24 : }
191 : }
192 :
193 : impl FromStr for $t {
194 : type Err = hex::FromHexError;
195 :
196 15053 : fn from_str(s: &str) -> Result<$t, Self::Err> {
197 15053 : let value = Id::from_str(s)?;
198 15044 : Ok($t(value))
199 15053 : }
200 : }
201 :
202 : impl From<[u8; 16]> for $t {
203 270550 : fn from(b: [u8; 16]) -> Self {
204 270550 : $t(Id::from(b))
205 270550 : }
206 : }
207 :
208 : impl FromHex for $t {
209 : type Error = hex::FromHexError;
210 :
211 108 : fn from_hex<T: AsRef<[u8]>>(hex: T) -> Result<Self, Self::Error> {
212 108 : Ok($t(Id::from_hex(hex)?))
213 108 : }
214 : }
215 :
216 : impl AsRef<[u8]> for $t {
217 16 : fn as_ref(&self) -> &[u8] {
218 16 : &self.0 .0
219 16 : }
220 : }
221 :
222 : impl From<$t> for u128 {
223 0 : fn from(id: $t) -> Self {
224 0 : u128::from(id.0)
225 0 : }
226 : }
227 :
228 : impl fmt::Display for $t {
229 204628 : fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
230 204628 : self.0.fmt(f)
231 204628 : }
232 : }
233 :
234 : impl fmt::Debug for $t {
235 9988 : fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
236 9988 : self.0.fmt(f)
237 9988 : }
238 : }
239 : };
240 : }
241 :
242 : /// Neon timeline ID.
243 : ///
244 : /// They are different from PostgreSQL timeline
245 : /// IDs, but serve a similar purpose: they differentiate
246 : /// between different "histories" of the same cluster. However,
247 : /// PostgreSQL timeline IDs are a bit cumbersome, because they are only
248 : /// 32-bits wide, and they must be in ascending order in any given
249 : /// timeline history. Those limitations mean that we cannot generate a
250 : /// new PostgreSQL timeline ID by just generating a random number. And
251 : /// that in turn is problematic for the "pull/push" workflow, where you
252 : /// have a local copy of a Neon repository, and you periodically sync
253 : /// the local changes with a remote server. When you work "detached"
254 : /// from the remote server, you cannot create a PostgreSQL timeline ID
255 : /// that's guaranteed to be different from all existing timelines in
256 : /// the remote server. For example, if two people are having a clone of
257 : /// the repository on their laptops, and they both create a new branch
258 : /// with different name. What timeline ID would they assign to their
259 : /// branches? If they pick the same one, and later try to push the
260 : /// branches to the same remote server, they will get mixed up.
261 : ///
262 : /// To avoid those issues, Neon has its own concept of timelines that
263 : /// is separate from PostgreSQL timelines, and doesn't have those
264 : /// limitations. A Neon timeline is identified by a 128-bit ID, which
265 : /// is usually printed out as a hex string.
266 : ///
267 : /// NOTE: It (de)serializes as an array of hex bytes, so the string representation would look
268 : /// like `[173,80,132,115,129,226,72,254,170,201,135,108,199,26,228,24]`.
269 : /// See [`Id`] for alternative ways to serialize it.
270 82312 : #[derive(Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd, Serialize, Deserialize)]
271 : pub struct TimelineId(Id);
272 :
273 : id_newtype!(TimelineId);
274 :
275 : impl TryFrom<Option<&str>> for TimelineId {
276 : type Error = anyhow::Error;
277 :
278 24 : fn try_from(value: Option<&str>) -> Result<Self, Self::Error> {
279 24 : value
280 24 : .unwrap_or_default()
281 24 : .parse::<TimelineId>()
282 24 : .with_context(|| format!("Could not parse timeline id from {:?}", value))
283 24 : }
284 : }
285 :
286 : /// Neon Tenant Id represents identifiar of a particular tenant.
287 : /// Is used for distinguishing requests and data belonging to different users.
288 : ///
289 : /// NOTE: It (de)serializes as an array of hex bytes, so the string representation would look
290 : /// like `[173,80,132,115,129,226,72,254,170,201,135,108,199,26,228,24]`.
291 : /// See [`Id`] for alternative ways to serialize it.
292 82219 : #[derive(Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, PartialOrd, Ord)]
293 : pub struct TenantId(Id);
294 :
295 : id_newtype!(TenantId);
296 :
297 : // A pair uniquely identifying Neon instance.
298 0 : #[derive(Debug, Clone, Copy, PartialOrd, Ord, PartialEq, Eq, Hash, Serialize, Deserialize)]
299 : pub struct TenantTimelineId {
300 : pub tenant_id: TenantId,
301 : pub timeline_id: TimelineId,
302 : }
303 :
304 : impl TenantTimelineId {
305 181842 : pub fn new(tenant_id: TenantId, timeline_id: TimelineId) -> Self {
306 181842 : TenantTimelineId {
307 181842 : tenant_id,
308 181842 : timeline_id,
309 181842 : }
310 181842 : }
311 :
312 2010 : pub fn generate() -> Self {
313 2010 : Self::new(TenantId::generate(), TimelineId::generate())
314 2010 : }
315 :
316 100327 : pub fn empty() -> Self {
317 100327 : Self::new(TenantId::from([0u8; 16]), TimelineId::from([0u8; 16]))
318 100327 : }
319 : }
320 :
321 : impl fmt::Display for TenantTimelineId {
322 51 : fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
323 51 : write!(f, "{}/{}", self.tenant_id, self.timeline_id)
324 51 : }
325 : }
326 :
327 : impl FromStr for TenantTimelineId {
328 : type Err = anyhow::Error;
329 :
330 0 : fn from_str(s: &str) -> Result<Self, Self::Err> {
331 0 : let mut parts = s.split('/');
332 0 : let tenant_id = parts
333 0 : .next()
334 0 : .ok_or_else(|| anyhow::anyhow!("TenantTimelineId must contain tenant_id"))?
335 0 : .parse()?;
336 0 : let timeline_id = parts
337 0 : .next()
338 0 : .ok_or_else(|| anyhow::anyhow!("TenantTimelineId must contain timeline_id"))?
339 0 : .parse()?;
340 0 : if parts.next().is_some() {
341 0 : anyhow::bail!("TenantTimelineId must contain only tenant_id and timeline_id");
342 0 : }
343 0 : Ok(TenantTimelineId::new(tenant_id, timeline_id))
344 0 : }
345 : }
346 :
347 : // Unique ID of a storage node (safekeeper or pageserver). Supposed to be issued
348 : // by the console.
349 2 : #[derive(Clone, Copy, Eq, Ord, PartialEq, PartialOrd, Hash, Debug, Serialize, Deserialize)]
350 : #[serde(transparent)]
351 : pub struct NodeId(pub u64);
352 :
353 : impl fmt::Display for NodeId {
354 6 : fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
355 6 : write!(f, "{}", self.0)
356 6 : }
357 : }
358 :
359 : impl FromStr for NodeId {
360 : type Err = ParseIntError;
361 0 : fn from_str(s: &str) -> Result<Self, Self::Err> {
362 0 : Ok(NodeId(u64::from_str(s)?))
363 0 : }
364 : }
365 :
366 : #[cfg(test)]
367 : mod tests {
368 : use serde_assert::{Deserializer, Serializer, Token, Tokens};
369 :
370 : use crate::bin_ser::BeSer;
371 :
372 : use super::*;
373 :
374 : #[test]
375 1 : fn test_id_serde_non_human_readable() {
376 1 : let original_id = Id([
377 1 : 173, 80, 132, 115, 129, 226, 72, 254, 170, 201, 135, 108, 199, 26, 228, 24,
378 1 : ]);
379 1 : let expected_tokens = Tokens(vec![
380 1 : Token::Tuple { len: 16 },
381 1 : Token::U8(173),
382 1 : Token::U8(80),
383 1 : Token::U8(132),
384 1 : Token::U8(115),
385 1 : Token::U8(129),
386 1 : Token::U8(226),
387 1 : Token::U8(72),
388 1 : Token::U8(254),
389 1 : Token::U8(170),
390 1 : Token::U8(201),
391 1 : Token::U8(135),
392 1 : Token::U8(108),
393 1 : Token::U8(199),
394 1 : Token::U8(26),
395 1 : Token::U8(228),
396 1 : Token::U8(24),
397 1 : Token::TupleEnd,
398 1 : ]);
399 1 :
400 1 : let serializer = Serializer::builder().is_human_readable(false).build();
401 1 : let serialized_tokens = original_id.serialize(&serializer).unwrap();
402 1 : assert_eq!(serialized_tokens, expected_tokens);
403 :
404 1 : let mut deserializer = Deserializer::builder()
405 1 : .is_human_readable(false)
406 1 : .tokens(serialized_tokens)
407 1 : .build();
408 1 : let deserialized_id = Id::deserialize(&mut deserializer).unwrap();
409 1 : assert_eq!(deserialized_id, original_id);
410 1 : }
411 :
412 : #[test]
413 1 : fn test_id_serde_human_readable() {
414 1 : let original_id = Id([
415 1 : 173, 80, 132, 115, 129, 226, 72, 254, 170, 201, 135, 108, 199, 26, 228, 24,
416 1 : ]);
417 1 : let expected_tokens = Tokens(vec![Token::Str(String::from(
418 1 : "ad50847381e248feaac9876cc71ae418",
419 1 : ))]);
420 1 :
421 1 : let serializer = Serializer::builder().is_human_readable(true).build();
422 1 : let serialized_tokens = original_id.serialize(&serializer).unwrap();
423 1 : assert_eq!(serialized_tokens, expected_tokens);
424 :
425 1 : let mut deserializer = Deserializer::builder()
426 1 : .is_human_readable(true)
427 1 : .tokens(Tokens(vec![Token::Str(String::from(
428 1 : "ad50847381e248feaac9876cc71ae418",
429 1 : ))]))
430 1 : .build();
431 1 : assert_eq!(Id::deserialize(&mut deserializer).unwrap(), original_id);
432 1 : }
433 :
434 : macro_rules! roundtrip_type {
435 : ($type:ty, $expected_bytes:expr) => {{
436 : let expected_bytes: [u8; 16] = $expected_bytes;
437 : let original_id = <$type>::from(expected_bytes);
438 :
439 : let ser_bytes = original_id.ser().unwrap();
440 : assert_eq!(ser_bytes, expected_bytes);
441 :
442 : let des_id = <$type>::des(&ser_bytes).unwrap();
443 : assert_eq!(des_id, original_id);
444 : }};
445 : }
446 :
447 : #[test]
448 1 : fn test_id_bincode_serde() {
449 1 : let expected_bytes = [
450 1 : 173, 80, 132, 115, 129, 226, 72, 254, 170, 201, 135, 108, 199, 26, 228, 24,
451 1 : ];
452 1 :
453 1 : roundtrip_type!(Id, expected_bytes);
454 1 : }
455 :
456 : #[test]
457 1 : fn test_tenant_id_bincode_serde() {
458 1 : let expected_bytes = [
459 1 : 173, 80, 132, 115, 129, 226, 72, 254, 170, 201, 135, 108, 199, 26, 228, 24,
460 1 : ];
461 1 :
462 1 : roundtrip_type!(TenantId, expected_bytes);
463 1 : }
464 :
465 : #[test]
466 1 : fn test_timeline_id_bincode_serde() {
467 1 : let expected_bytes = [
468 1 : 173, 80, 132, 115, 129, 226, 72, 254, 170, 201, 135, 108, 199, 26, 228, 24,
469 1 : ];
470 1 :
471 1 : roundtrip_type!(TimelineId, expected_bytes);
472 1 : }
473 : }
|
