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