ic_db/store/maintenance/
mod.rs1mod copy;
3use super::{Database, Map, live_manifest, manifest_key, query, read_revision};
4use crate::{
5 Entity, Error, QueryCursor, QueryPage, Schema,
6 codec::{Decoder, Encoder},
7};
8pub use copy::{CopyStep, RetiredSource, SchemaCopy};
9use ic_storage::{DefaultMemoryImpl, Memory, RuntimeMemory};
10use sha2::{Digest, Sha256};
11
12pub(super) const MAGIC: &[u8; 8] = b"ICDBMT02";
13const MAX_NAME: usize = 64;
14const MAX_INPUTS: usize = 256;
15const MAX_FRAME: usize = 421;
16
17pub(super) fn admits_gate(bytes: &[u8]) -> Result<bool, Error> {
18 if bytes.starts_with(MAGIC) {
19 decode(bytes)?;
20 } else if bytes.starts_with(copy::MAGIC) {
21 copy::decode(bytes)?;
22 } else {
23 return Ok(false);
24 }
25 Ok(true)
26}
27
28#[derive(Clone, Debug, PartialEq, Eq)]
32pub struct SchemaTransition {
33 source: [u8; 32],
34 target: [u8; 32],
35 name: String,
36 version: u32,
37 inputs: Vec<u8>,
38}
39
40impl SchemaTransition {
41 pub fn new(
46 source: &Schema,
47 target: &Schema,
48 name: &str,
49 version: u32,
50 inputs: &[u8],
51 ) -> Result<Self, Error> {
52 if source.fingerprint() == target.fingerprint()
53 || name.is_empty()
54 || name.len() > MAX_NAME
55 || version == 0
56 || inputs.len() > MAX_INPUTS
57 {
58 return Err(Error::InvalidTransition);
59 }
60 Ok(Self {
61 source: source.fingerprint(),
62 target: target.fingerprint(),
63 name: name.into(),
64 version,
65 inputs: inputs.into(),
66 })
67 }
68 #[must_use]
70 pub const fn source(&self) -> [u8; 32] {
71 self.source
72 }
73 #[must_use]
75 pub const fn target(&self) -> [u8; 32] {
76 self.target
77 }
78 #[must_use]
80 pub fn name(&self) -> &str {
81 &self.name
82 }
83 #[must_use]
85 pub const fn version(&self) -> u32 {
86 self.version
87 }
88 #[must_use]
90 pub fn inputs(&self) -> &[u8] {
91 &self.inputs
92 }
93
94 fn freeze(&self, incarnation: [u8; 16]) -> Result<Vec<u8>, Error> {
95 let mut payload = Encoder::new();
96 payload.nat8(0)?; payload.nat32(self.version)?;
98 payload.bytes(self.name.as_bytes())?;
99 payload.bytes(&self.inputs)?;
100 let mut bytes = MAGIC.to_vec();
101 bytes.extend(self.source);
102 bytes.extend(self.target);
103 bytes.extend(incarnation);
104 bytes.extend(payload.finish());
105 Ok(bytes)
106 }
107}
108
109pub struct Maintenance<M: Memory = DefaultMemoryImpl> {
113 map: Map<M>,
114 transition: SchemaTransition,
115 incarnation: [u8; 16],
116}
117
118impl<M: Memory> Database<M> {
119 pub fn begin_maintenance(
127 mut self,
128 transition: &SchemaTransition,
129 ) -> Result<Maintenance<M>, Error> {
130 if transition.source != self.schema.fingerprint() {
131 return Err(Error::InvalidTransition);
132 }
133 let bytes = transition.freeze(self.incarnation)?;
134 let transition = transition.clone();
135 self.map.insert(manifest_key(), bytes);
136 Ok(Maintenance {
137 map: self.map,
138 transition,
139 incarnation: self.incarnation,
140 })
141 }
142}
143
144impl<M: Memory> Maintenance<M> {
145 pub fn resume(memory: RuntimeMemory<M>, expected: &SchemaTransition) -> Result<Self, Error> {
151 if memory.size() == 0 {
152 return Err(Error::Corrupt);
153 }
154 let map = Map::load(memory);
155 let bytes = map.get(&manifest_key()).ok_or(Error::Corrupt)?;
156 let (transition, incarnation) = decode(&bytes)?;
157 if transition != *expected {
158 return Err(Error::InvalidTransition);
159 }
160 Ok(Self {
161 map,
162 transition,
163 incarnation,
164 })
165 }
166 #[must_use]
168 pub const fn transition(&self) -> &SchemaTransition {
169 &self.transition
170 }
171 #[must_use]
173 pub const fn incarnation(&self) -> [u8; 16] {
174 self.incarnation
175 }
176 pub fn source_page<E: Entity>(
189 &self,
190 source: &Schema,
191 after: Option<&QueryCursor>,
192 limit: usize,
193 bytes: usize,
194 ) -> Result<QueryPage<E>, Error> {
195 if source.fingerprint() != self.transition.source {
196 return Err(Error::IncompatibleSchema);
197 }
198 source.admits(E::SCHEMA)?;
199 let revision = read_revision(&self.map, E::ID)?;
200 let mut hash = Sha256::new();
201 hash.update(b"ic-db:maintenance-source:v1\0");
202 hash.update(self.transition.freeze(self.incarnation)?);
203 hash.update(revision.to_le_bytes());
204 query::source_page(
205 &self.map,
206 E::SCHEMA,
207 hash.finalize().into(),
208 self.incarnation,
209 after,
210 limit,
211 bytes,
212 )?
213 .decode_entities()
214 }
215 pub fn cancel(mut self) {
221 let bytes = live_manifest(self.transition.source, self.incarnation);
222 self.map.insert(manifest_key(), bytes);
223 }
224}
225
226pub(super) fn decode(bytes: &[u8]) -> Result<(SchemaTransition, [u8; 16]), Error> {
229 if !bytes.starts_with(MAGIC) {
230 return Err(Error::InvalidTransition);
231 }
232 if !(102..=MAX_FRAME).contains(&bytes.len()) {
233 return Err(Error::Corrupt);
234 }
235 let source = bytes[8..40].try_into().map_err(|_| Error::Corrupt)?;
236 let target = bytes[40..72].try_into().map_err(|_| Error::Corrupt)?;
237 let incarnation = bytes[72..88].try_into().map_err(|_| Error::Corrupt)?;
238 let mut reader = Decoder::new(&bytes[88..])?;
239 if reader.nat8()? != 0 {
240 return Err(Error::IncompatibleSchema);
241 }
242 let version = reader.nat32()?;
243 let name = reader.text(MAX_NAME)?;
244 let inputs = reader.blob(MAX_INPUTS)?;
245 reader.finish()?;
246 if source == target || incarnation == [0; 16] || version == 0 || name.is_empty() {
247 return Err(Error::Corrupt);
248 }
249 Ok((
250 SchemaTransition {
251 source,
252 target,
253 name,
254 version,
255 inputs,
256 },
257 incarnation,
258 ))
259}