pub struct SequencePosition(/* private fields */);Expand description
An event’s place in the store’s total order.
The specification requires positions to be unique and monotonically
increasing, and explicitly permits gaps — so this is an opaque ordering key,
not a count of events. Never compute end - start and call it a length.
Backed by NonZeroU64, which makes position zero unrepresentable and lets
Option<SequencePosition> occupy the same eight bytes as a bare
SequencePosition. That matters: Option<SequencePosition> appears in every
AppendCondition and every
ReadOptions.
§Examples
use happenstance_core::SequencePosition;
assert_eq!(SequencePosition::FIRST.get(), 1);
assert!(SequencePosition::new(0).is_none());
// The niche optimisation: no discriminant word is needed.
assert_eq!(
size_of::<Option<SequencePosition>>(),
size_of::<SequencePosition>(),
);Implementations§
Source§impl SequencePosition
impl SequencePosition
Sourcepub const fn get(self) -> u64
pub const fn get(self) -> u64
The underlying value.
Examples found in repository?
620async fn print_log(events: &SqliteEventStore) -> Result<()> {
621 let log = collect(events.read(&Query::all(), ReadOptions::new())).await?;
622
623 for event in log {
624 println!(
625 " {:>3} {:<15} {:?}",
626 event.position.get(),
627 event.event_type().as_str(),
628 event.tags()
629 );
630 }
631
632 Ok(())
633}More examples
1451async fn poison(
1452 events: &SqliteEventStore,
1453 models: &SqliteProjectionStore,
1454 projection: &mut Couriered,
1455) -> Result<(u64, String)> {
1456 let chunk = Chunk::of(CHUNK.try_into()?);
1457 match run_projection(events, models, projection, &Json, chunk).await {
1458 Ok(progress) => bail!(
1459 "the couriered view decoded {} event(s) it could not have",
1460 progress.applied
1461 ),
1462 Err(ProjectionError::Decode {
1463 position, source, ..
1464 }) => Ok((position.get(), error_chain(&source))),
1465 // `ProjectionError` is `#[non_exhaustive]`. A read failure or a commit
1466 // failure here would be a different defect wearing this one's clothes.
1467 Err(other) => bail!("expected a decode failure, got: {other}"),
1468 }
1469}
1470
1471/// Renders an error and everything under it, joined by `: `.
1472///
1473/// `CodecError`'s own `Display` says the payload could not be decoded, which
1474/// is a category. The value a reader needs — *which field was missing* — is
1475/// one link down the source chain, and a message that stops at the top of that
1476/// chain is the same defect `rejected` exists to avoid one layer up.
1477fn error_chain(error: &dyn core::error::Error) -> String {
1478 let mut rendered = error.to_string();
1479 let mut source = error.source();
1480
1481 while let Some(cause) = source {
1482 rendered.push_str(": ");
1483 rendered.push_str(&cause.to_string());
1484 source = cause.source();
1485 }
1486
1487 rendered
1488}
1489
1490/// Clears a view's rows and its checkpoint as one unit of work.
1491///
1492/// The statements are the *application's*, because the read model is: the port
1493/// takes a batch and commits it alongside the checkpoint reset, and it has no
1494/// idea which tables this program invented. Used for the two things reset is
1495/// actually for — retiring a view, and preparing a rebuild — and a retirement
1496/// may carry a blue/green swap, which is what puts the swap in the same
1497/// transaction as the checkpoint it retires.
1498///
1499/// A slice of statements rather than one string of several: the batch runs one
1500/// statement per `push`, and rusqlite refuses a push that holds two with
1501/// `MultipleStatement` — at commit, after the batch has left this function.
1502///
1503/// It takes the projection rather than an id, so the reset names the id the
1504/// runner commits under, `checkpoint_id`. A reset of `projection.id()`, the
1505/// bare name, clears a row the runner never wrote and leaves its checkpoint
1506/// standing.
1507async fn retire<P: Projection>(
1508 models: &SqliteProjectionStore,
1509 projection: &P,
1510 statements: &[&'static str],
1511) -> Result<()> {
1512 let key = checkpoint_id(projection)?;
1513 let mut batch = models.begin().await?;
1514 for statement in statements {
1515 batch.push(statement, []);
1516 }
1517 models.reset(batch, &key).await?;
1518 Ok(())
1519}
1520
1521/// Prints where a view has got to, under its name.
1522///
1523/// Read through `checkpoint_id` for the reason `retire` resets through it:
1524/// the bare name reads `never run` whatever the runner did.
1525async fn print_checkpoint<P: Projection>(
1526 models: &SqliteProjectionStore,
1527 projection: &P,
1528) -> Result<()> {
1529 let name = projection.id();
1530 let checkpoint = render_checkpoint(models.checkpoint(&checkpoint_id(projection)?).await?);
1531 writeln!(io::stdout().lock(), " {name} is {checkpoint}")?;
1532 Ok(())
1533}
1534
1535/// Renders a checkpoint as the transcript prints it.
1536fn render_checkpoint(checkpoint: Checkpoint) -> String {
1537 match checkpoint {
1538 Checkpoint::NeverRun => "never run".to_owned(),
1539 Checkpoint::Live { through } => format!("live through {through}"),
1540 Checkpoint::Rebuilding { through } => format!("rebuilding through {through}"),
1541 // `Checkpoint` is `#[non_exhaustive]`, so the wildcard is required. It
1542 // is not laziness: a fourth state added upstream must not silently
1543 // render as one of these three.
1544 other => format!("{other:?}"),
1545 }
1546}
1547
1548// ---------------------------------------------------------------------------
1549// Reading what the views wrote
1550// ---------------------------------------------------------------------------
1551
1552/// Prints a read-model query's rows, three spaces in.
1553fn print_table(app: &Connection, sql: &str) -> Result<()> {
1554 let rows = render_table(app, sql)?;
1555 write!(io::stdout().lock(), "{rows}")?;
1556 Ok(())
1557}
1558
1559/// Renders a read-model query's rows, so two of them can be compared.
1560///
1561/// Every column comes back as a `rusqlite::types::Value` rather than as a
1562/// typed `get`, because this one function serves five tables with different
1563/// column types and a typed read would need one function per table.
1564fn render_table(app: &Connection, sql: &str) -> Result<String> {
1565 let mut statement = app.prepare(sql)?;
1566 let columns = statement.column_count();
1567 let mut rows = statement.query([])?;
1568 let mut rendered = String::new();
1569
1570 while let Some(row) = rows.next()? {
1571 let mut cells = Vec::with_capacity(columns);
1572 for index in 0..columns {
1573 cells.push(render_cell(&row.get::<_, Value>(index)?));
1574 }
1575 rendered.push_str(" ");
1576 rendered.push_str(&cells.join(" "));
1577 rendered.push('\n');
1578 }
1579
1580 Ok(rendered)
1581}
1582
1583/// Renders one cell of a read-model row.
1584fn render_cell(value: &Value) -> String {
1585 match value {
1586 Value::Null => "NULL".to_owned(),
1587 Value::Integer(number) => format!("{number}"),
1588 Value::Real(number) => format!("{number}"),
1589 Value::Text(text) => text.clone(),
1590 Value::Blob(bytes) => format!("<{} bytes>", bytes.len()),
1591 }
1592}
1593
1594/// Prints every event in the store, in the order the store assigned.
1595async fn print_log(events: &SqliteEventStore) -> Result<()> {
1596 let log = collect(events.read(&Query::all(), ReadOptions::new())).await?;
1597
1598 for event in log {
1599 writeln!(
1600 io::stdout().lock(),
1601 " {:>3} {:<16} {:?}",
1602 event.position.get(),
1603 event.event_type().as_str(),
1604 event.tags()
1605 )?;
1606 }
1607
1608 Ok(())
1609}171async fn one_log_two_encodings(events: &SqliteEventStore) -> Result<()> {
172 println!("\n== one log, two encodings ==");
173
174 let log = collect(events.read(&Query::all(), ReadOptions::new())).await?;
175 let mut seen = Vec::new();
176
177 for event in &log {
178 let codec = framed_codec(event).unwrap_or_else(|| "unframed".to_owned());
179 println!(
180 " {:>3} {:<22} {:<8} {} bytes",
181 event.position.get(),
182 event.event_type().as_str(),
183 codec,
184 event.event.data().len()
185 );
186 if !seen.contains(&codec) {
187 seen.push(codec);
188 }
189 }
190
191 if seen.len() < 2 {
192 bail!("the log holds only {seen:?}, so there are no two encodings to read across");
193 }
194 println!(" two encodings and two temperature types, in one store, side by side");
195
196 Ok(())
197}
198
199/// Folds the whole device history with one codec in hand.
200///
201/// The section the other three exist for. `Json` is the only codec named at
202/// this call site; the postcard readings arrive decoded anyway, because the
203/// framing region says what they were written with. The v1 readings arrive
204/// *upcast*, because `Telemetry::decode` was handed their event type and knew
205/// what to do with it.
206async fn one_fold_reads_both(events: &SqliteEventStore) -> Result<()> {
207 println!("\n== one fold reads both ==");
208
209 let device = DeviceId::new(DEVICE)?;
210 let mut readings = Readings::new(&device)?;
211
212 let query = readings.query()?;
213 let (found, _) = read_decision_model(events, &query).await?;
214 for event in &found {
215 readings.absorb(event, &Json)?;
216 }
217
218 println!(
219 " the derived query nominated {} event(s), and one codec was named here: Json",
220 found.len()
221 );
222 println!(
223 " firmware: {}",
224 readings.firmware.as_deref().unwrap_or("unknown")
225 );
226 println!(" readings: {:?}", readings.millidegrees);
227
228 // The upcast is the assertion. 21 degrees was written by a binary that had
229 // never heard of a thousandth, and it is 21000 here without anything in
230 // this function converting it.
231 if !readings.millidegrees.contains(&(21 * PER_DEGREE)) {
232 bail!(
233 "the first JSON reading did not arrive upcast: {:?}",
234 readings.millidegrees
235 );
236 }
237 println!(
238 " 21 whole degrees, written by a binary with no concept of a\n \
239 thousandth, arrives as {} — the upcast is in `decode`, and the fold\n \
240 below it has one temperature variant and no idea there were ever two",
241 21 * PER_DEGREE
242 );
243
244 Ok(())
245}
246
247// ---------------------------------------------------------------------------
248// Identity, validated once at the edge
249// ---------------------------------------------------------------------------
250
251/// A device, validated once into the tag its events carry.
252///
253/// The resolution the other examples reach, and for the same reason:
254/// `DomainEvent::tags` is infallible while `Tag::key_value` can refuse, so a
255/// domain type whose tags come from runtime values holds the validated form
256/// instead of rebuilding it on every call.
257#[derive(Debug, Clone, Serialize, Deserialize)]
258#[serde(try_from = "String", into = "String")]
259struct DeviceId {
260 /// The identifier as the application wrote it.
261 id: String,
262 /// The same value, validated into a tag.
263 tag: Tag,
264}
265
266impl DeviceId {
267 /// Validates `id` into the tag every event for this device is written with.
268 fn new(id: &str) -> Result<Self, InvalidTag> {
269 Ok(Self {
270 id: id.to_owned(),
271 tag: Tag::key_value("device", id)?,
272 })
273 }
274
275 /// The identifier as the application wrote it.
276 fn as_str(&self) -> &str {
277 &self.id
278 }
279}
280
281impl TryFrom<String> for DeviceId {
282 type Error = InvalidTag;
283
284 fn try_from(id: String) -> Result<Self, InvalidTag> {
285 Self::new(&id)
286 }
287}
288
289impl From<DeviceId> for String {
290 fn from(device: DeviceId) -> Self {
291 device.id
292 }
293}
294
295// ---------------------------------------------------------------------------
296// The domain, in the shape the old binary had
297// ---------------------------------------------------------------------------
298
299/// The event set the previous version of this application shipped.
300///
301/// **Kept rather than deleted, and it is not dead code.** It is the wire
302/// format of every reading written before the upgrade, and `Telemetry::decode`
303/// still reaches for it — an upcast is "decode with the type that wrote these
304/// bytes, then map forward", and the type that wrote them has to still exist
305/// for that sentence to be executable.
306///
307/// It writes two event types. `Telemetry` declares four, because it must
308/// nominate these two as well as its own.
309#[derive(Debug, Serialize, Deserialize)]
310enum Legacy {
311 /// A device came online. The same shape the new version writes.
312 DeviceRegistered {
313 /// The device now known.
314 device: DeviceId,
315 /// What it was running.
316 firmware: String,
317 },
318 /// A reading, in whole degrees Celsius.
319 TemperatureReported {
320 /// Which device reported.
321 device: DeviceId,
322 /// The reading, in whole degrees.
323 celsius: i32,
324 },
325}
326
327/// The four names this log has ever carried, declared once.
328///
329/// Two of them mean the same *reading* at different schema versions, and that is
330/// the whole point of this example — so they are named rather than indexed.
331/// Indexing the declaration list gave two subscripts that differ by one
332/// character and mean "what is written now" and "what may still be read";
333/// `TEMPERATURE_REPORTED_V2` and `TEMPERATURE_REPORTED` cannot be confused by a
334/// reader, or reordered into a lie by an editor.
335const DEVICE_REGISTERED: EventType = EventType::from_static("DeviceRegistered");
336/// See [`DEVICE_REGISTERED`].
337const FIRMWARE_UPGRADED: EventType = EventType::from_static("FirmwareUpgraded");
338/// The **v1** reading. Read-only: nothing writes this name any more.
339const TEMPERATURE_REPORTED: EventType = EventType::from_static("TemperatureReported");
340/// The **v2** reading, and what a reading written now carries.
341const TEMPERATURE_REPORTED_V2: EventType = EventType::from_static("TemperatureReportedV2");
342
343impl DomainEvent for Legacy {
344 const EVENT_TYPES: &'static [EventType] = &[DEVICE_REGISTERED, TEMPERATURE_REPORTED];
345
346 fn event_type(&self) -> EventType {
347 match self {
348 Self::DeviceRegistered { .. } => DEVICE_REGISTERED,
349 Self::TemperatureReported { .. } => TEMPERATURE_REPORTED,
350 }
351 }
352
353 fn tags(&self) -> Tags {
354 match self {
355 Self::DeviceRegistered { device, .. } | Self::TemperatureReported { device, .. } => {
356 [device.tag.clone()].into_iter().collect()
357 }
358 }
359 }
360
361 fn encode<C: Codec>(&self, codec: &C) -> Result<Bytes, CodecError> {
362 codec.encode(self)
363 }
364
365 fn decode<C: Codec>(
366 codec: &C,
367 _event_type: &EventType,
368 data: &Bytes,
369 ) -> Result<Self, CodecError> {
370 codec.decode(data)
371 }
372}
373
374// ---------------------------------------------------------------------------
375// The domain, as it is now
376// ---------------------------------------------------------------------------
377
378/// Everything that can happen to a device, in this version's vocabulary.
379///
380/// One temperature variant, in thousandths. The fold does not know there were
381/// ever two shapes, and that is the whole reason the upcast lives in `decode`
382/// rather than in every `apply` that has to deal with a reading.
383#[derive(Debug, Serialize, Deserialize)]
384enum Telemetry {
385 /// A device came online.
386 DeviceRegistered {
387 /// The device now known.
388 device: DeviceId,
389 /// What it was running.
390 firmware: String,
391 },
392 /// A device's firmware changed.
393 FirmwareUpgraded {
394 /// The device upgraded.
395 device: DeviceId,
396 /// What it is running now.
397 firmware: String,
398 },
399 /// A reading, in thousandths of a degree.
400 TemperatureReported {
401 /// Which device reported.
402 device: DeviceId,
403 /// The reading, in thousandths of a degree.
404 millidegrees: i32,
405 },
406}
407
408impl DomainEvent for Telemetry {
409 /// Four names for three variants.
410 ///
411 /// `TemperatureReported` is the **old** name and nothing writes it any
412 /// more. It is declared because the query is derived from this list, so
413 /// removing it would stop every boundary nominating the readings written
414 /// before the upgrade — silently, and with no test, lint or conformance
415 /// rule that has an opinion. The list is where a log's past is kept alive.
416 const EVENT_TYPES: &'static [EventType] = &[
417 DEVICE_REGISTERED,
418 FIRMWARE_UPGRADED,
419 TEMPERATURE_REPORTED,
420 TEMPERATURE_REPORTED_V2,
421 ];
422
423 fn event_type(&self) -> EventType {
424 match self {
425 Self::DeviceRegistered { .. } => DEVICE_REGISTERED,
426 Self::FirmwareUpgraded { .. } => FIRMWARE_UPGRADED,
427 // The v2 name, never the v1 one. A reading written now is a v2
428 // reading; the v1 name is read-only. This used to be a subscript
429 // into the list above, carried by a comment saying "index 3, never
430 // index 2" — the comment a named constant makes unnecessary.
431 Self::TemperatureReported { .. } => TEMPERATURE_REPORTED_V2,
432 }
433 }
434
435 fn tags(&self) -> Tags {
436 match self {
437 Self::DeviceRegistered { device, .. }
438 | Self::FirmwareUpgraded { device, .. }
439 | Self::TemperatureReported { device, .. } => {
440 [device.tag.clone()].into_iter().collect()
441 }
442 }
443 }
444
445 fn encode<C: Codec>(&self, codec: &C) -> Result<Bytes, CodecError> {
446 codec.encode(self)
447 }
448
449 /// Decodes a payload written for `event_type`, upcasting the old shape.
450 ///
451 /// **The one place in this workspace where that parameter is used.** The
452 /// codec tag in the framing region has already decided *how* these bytes
453 /// were encoded; what it cannot decide is what they meant, because a v1
454 /// reading deserialises perfectly into a number that is a thousand times
455 /// too small. Only the event type distinguishes them.
456 fn decode<C: Codec>(
457 codec: &C,
458 event_type: &EventType,
459 data: &Bytes,
460 ) -> Result<Self, CodecError> {
461 // The named v1 constant, not the literal `"TemperatureReported"`: one
462 // declaration, so there is no second spelling to get wrong.
463 if *event_type == TEMPERATURE_REPORTED {
464 return Ok(upcast(codec.decode::<Legacy>(data)?));
465 }
466
467 codec.decode(data)
468 }
469}
470
471/// Maps an event written by the previous version into this one's vocabulary.
472///
473/// Total, and deliberately so: an upcast that can fail is a log that can stop
474/// being readable, and there is nothing a caller could do about it at the
475/// moment it happens. Whole degrees multiply into thousandths exactly, so the
476/// conversion loses nothing — `i32` covers the plausible range this
477/// application accepts several hundred times over.
478fn upcast(old: Legacy) -> Telemetry {
479 match old {
480 Legacy::DeviceRegistered { device, firmware } => {
481 Telemetry::DeviceRegistered { device, firmware }
482 }
483 Legacy::TemperatureReported { device, celsius } => Telemetry::TemperatureReported {
484 device,
485 millidegrees: celsius.saturating_mul(PER_DEGREE),
486 },
487 }
488}
489
490/// Why a decision refused.
491///
492/// Every variant carries the value the transcript prints — `900000 is outside
493/// -60000..=150000` and never `invalid reading` — so a reader can act on the
494/// refusal where it is printed.
495#[derive(Debug, thiserror::Error)]
496enum Refusal {
497 /// Nothing can be reported for a device nobody registered.
498 #[error("device {device} is not registered")]
499 NotRegistered {
500 /// The unknown device.
501 device: String,
502 },
503 /// A device registers once.
504 #[error("device {device} is already registered")]
505 AlreadyRegistered {
506 /// The device already known.
507 device: String,
508 },
509 /// A reading outside the range this application accepts.
510 #[error("{millidegrees} is outside {MIN_MILLIDEGREES}..={MAX_MILLIDEGREES}")]
511 Implausible {
512 /// The reading that was refused.
513 millidegrees: i32,
514 },
515}
516
517// ---------------------------------------------------------------------------
518// The decision models
519// ---------------------------------------------------------------------------
520
521/// One device's history, as the old binary saw it.
522///
523/// It exists to write the old log honestly. Its query is derived from
524/// `Legacy::EVENT_TYPES`, which is the two names that version knew — which is
525/// exactly the boundary the old binary had, and exactly why the new one has to
526/// declare four.
527#[derive(Debug, Clone)]
528struct LegacyDevice {
529 /// The tags every event inside this boundary carries.
530 scope: Tags,
531 /// Whether the device has been registered.
532 registered: bool,
533}
534
535impl LegacyDevice {
536 /// Validates the scope once, here, where the caller already writes a `?`.
537 fn new(device: &DeviceId) -> Result<Self, InvalidTag> {
538 Ok(Self {
539 scope: Tags::from_pairs([("device", device.as_str())])?,
540 registered: false,
541 })
542 }
543}
544
545impl DecisionModel for LegacyDevice {
546 type Event = Legacy;
547
548 fn scope(&self) -> &Tags {
549 &self.scope
550 }
551
552 fn apply(&mut self, event: Self::Event) {
553 match event {
554 Legacy::DeviceRegistered { .. } => self.registered = true,
555 // A reading changes nothing this model decides on. The arm exists
556 // because the fold is exhaustive over the enum, and that
557 // exhaustiveness is the whole guarantee.
558 Legacy::TemperatureReported { .. } => {}
559 }
560 }
561}
562
563/// One device's history, in this version's vocabulary.
564///
565/// Its `millidegrees` holds every reading the boundary nominated, from both
566/// eras, in one unit. There is no branch in `apply` that knows about the
567/// upgrade, because by the time an event reaches `apply` it has already been
568/// upcast.
569#[derive(Debug, Clone)]
570struct Readings {
571 /// The tags every event inside this boundary carries.
572 scope: Tags,
573 /// Whether the device has been registered.
574 registered: bool,
575 /// What it is running now, once anything has said.
576 firmware: Option<String>,
577 /// Every reading the boundary nominated, in thousandths of a degree.
578 millidegrees: Vec<i32>,
579}
580
581impl Readings {
582 /// Validates the scope once, here, where the caller already writes a `?`.
583 fn new(device: &DeviceId) -> Result<Self, InvalidTag> {
584 Ok(Self {
585 scope: Tags::from_pairs([("device", device.as_str())])?,
586 registered: false,
587 firmware: None,
588 millidegrees: Vec::new(),
589 })
590 }
591}
592
593impl DecisionModel for Readings {
594 type Event = Telemetry;
595
596 fn scope(&self) -> &Tags {
597 &self.scope
598 }
599
600 fn apply(&mut self, event: Self::Event) {
601 match event {
602 Telemetry::DeviceRegistered { firmware, .. } => {
603 self.registered = true;
604 self.firmware = Some(firmware);
605 }
606 Telemetry::FirmwareUpgraded { firmware, .. } => self.firmware = Some(firmware),
607 Telemetry::TemperatureReported { millidegrees, .. } => {
608 self.millidegrees.push(millidegrees);
609 }
610 }
611 }
612}
613
614// ---------------------------------------------------------------------------
615// The command handlers, in two generations
616// ---------------------------------------------------------------------------
617
618/// Registers a device, as the old binary did: `commit`, so JSON.
619async fn register(events: &SqliteEventStore, device: &str, firmware: &str) -> Result<()> {
620 let device = DeviceId::new(device)?;
621 let boundary = LegacyDevice::new(&device)?;
622
623 commit(
624 events,
625 boundary,
626 Retry::attempts(ATTEMPTS.try_into()?),
627 |known: &LegacyDevice| {
628 if known.registered {
629 return Err(Refusal::AlreadyRegistered {
630 device: device.id.clone(),
631 });
632 }
633 Ok(vec![Legacy::DeviceRegistered {
634 device: device.clone(),
635 firmware: firmware.to_owned(),
636 }])
637 },
638 )
639 .await
640 .map(|_| ())
641 .map_err(rejected)
642}
643
644/// Reports a reading in whole degrees, as the old binary did: `commit`, so JSON.
645async fn report_celsius(events: &SqliteEventStore, device: &str, celsius: i32) -> Result<()> {
646 let device = DeviceId::new(device)?;
647 let boundary = LegacyDevice::new(&device)?;
648
649 commit(
650 events,
651 boundary,
652 Retry::attempts(ATTEMPTS.try_into()?),
653 |known: &LegacyDevice| {
654 if !known.registered {
655 return Err(Refusal::NotRegistered {
656 device: device.id.clone(),
657 });
658 }
659 Ok(vec![Legacy::TemperatureReported {
660 device: device.clone(),
661 celsius,
662 }])
663 },
664 )
665 .await
666 .map(|_| ())
667 .map_err(rejected)
668}
669
670/// Records a firmware upgrade, in the new encoding.
671async fn upgrade_firmware(events: &SqliteEventStore, device: &str, firmware: &str) -> Result<()> {
672 let device = DeviceId::new(device)?;
673 let boundary = Readings::new(&device)?;
674
675 commit_with(
676 events,
677 boundary,
678 &Postcard,
679 Retry::attempts(ATTEMPTS.try_into()?),
680 |known: &Readings| {
681 if !known.registered {
682 return Err(Refusal::NotRegistered {
683 device: device.id.clone(),
684 });
685 }
686 Ok(vec![Telemetry::FirmwareUpgraded {
687 device: device.clone(),
688 firmware: firmware.to_owned(),
689 }])
690 },
691 )
692 .await
693 .map(|_| ())
694 .map_err(rejected)
695}
696
697/// Reports a reading in thousandths, in the new encoding.
698///
699/// `commit_with` and an explicit `&Postcard`. It is the ungated entry point —
700/// `commit` is this function with `Json` already chosen — and naming the codec
701/// here is the only difference between this handler and the one above it that
702/// wrote JSON. The boundary it reads is a `Readings`, so this decision is taken
703/// against a fold that has already absorbed the *JSON* events written before
704/// the upgrade.
705async fn report_millidegrees(
706 events: &SqliteEventStore,
707 device: &str,
708 millidegrees: i32,
709) -> Result<()> {
710 let device = DeviceId::new(device)?;
711 let boundary = Readings::new(&device)?;
712
713 commit_with(
714 events,
715 boundary,
716 &Postcard,
717 Retry::attempts(ATTEMPTS.try_into()?),
718 |known: &Readings| {
719 if !known.registered {
720 return Err(Refusal::NotRegistered {
721 device: device.id.clone(),
722 });
723 }
724 if !(MIN_MILLIDEGREES..=MAX_MILLIDEGREES).contains(&millidegrees) {
725 return Err(Refusal::Implausible { millidegrees });
726 }
727 Ok(vec![Telemetry::TemperatureReported {
728 device: device.clone(),
729 millidegrees,
730 }])
731 },
732 )
733 .await
734 .map(|_| ())
735 .map_err(rejected)
736}
737
738// ---------------------------------------------------------------------------
739// Reading
740// ---------------------------------------------------------------------------
741
742/// The codec tag an event was framed with, read out of its metadata.
743///
744/// **Nothing needs this.** The framing region is documented as opaque to
745/// stores and adapters, and the decode path resolves it without any caller
746/// looking; it is parsed here so the transcript can show that two encodings
747/// really are sitting in one log. Every step is fallible and none of it
748/// panics: an event written by something that does not frame its payloads at
749/// all is a legitimate thing to meet, and it renders as `unframed`.
750fn framed_codec(event: &SequencedEvent) -> Option<String> {
751 let metadata = event.event.metadata()?;
752 let after_magic = metadata.strip_prefix(b"hpst\x01")?;
753 let end = after_magic.iter().position(|byte| *byte == 0xFF)?;
754
755 core::str::from_utf8(&after_magic[..end])
756 .ok()
757 .map(str::to_owned)
758}
759
760/// Prints every event in the store, in the order the store assigned.
761async fn print_log(events: &SqliteEventStore) -> Result<()> {
762 let log = collect(events.read(&Query::all(), ReadOptions::new())).await?;
763
764 for event in log {
765 println!(
766 " {:>3} {:<22} {:?}",
767 event.position.get(),
768 event.event_type().as_str(),
769 event.tags()
770 );
771 }
772
773 Ok(())
774}29async fn main() -> Result<()> {
30 let store = MemoryEventStore::new();
31
32 println!("== defining course c1 with capacity 2 ==");
33 define_course(&store, "c1", 2).await?;
34 println!(" defined");
35
36 println!("\n== defining course c1 again ==");
37 match define_course(&store, "c1", 5).await {
38 Ok(()) => bail!("a duplicate course definition should have been rejected"),
39 Err(err) => println!(" rejected: {err}"),
40 }
41
42 println!("\n== subscribing s1 and s2 ==");
43 subscribe(&store, "c1", "s1").await?;
44 subscribe(&store, "c1", "s2").await?;
45 println!(" both subscribed");
46
47 println!("\n== subscribing s1 again ==");
48 match subscribe(&store, "c1", "s1").await {
49 Ok(()) => bail!("a duplicate subscription should have been rejected"),
50 Err(err) => println!(" rejected: {err}"),
51 }
52
53 println!("\n== subscribing s3, which would exceed capacity ==");
54 match subscribe(&store, "c1", "s3").await {
55 Ok(()) => bail!("exceeding capacity should have been rejected"),
56 Err(err) => println!(" rejected: {err}"),
57 }
58
59 println!("\n== s1 unsubscribes, freeing a seat ==");
60 unsubscribe(&store, "c1", "s1").await?;
61 subscribe(&store, "c1", "s3").await?;
62 println!(" s3 subscribed into the freed seat");
63
64 println!("\n== final log ==");
65 for event in store.snapshot() {
66 println!(
67 " {:>3} {:<22} {:?}",
68 event.position.get(),
69 event.event_type().as_str(),
70 event.tags()
71 );
72 }
73
74 Ok(())
75}161async fn show_the_seats(state: &State, request: &Request, stream: &mut TcpStream) -> Result<()> {
162 let through = checkpoint_through(&state.models, &state.checkpoint).await?;
163 let checkpoint = through.map_or_else(|| "none".to_owned(), |position| position.to_string());
164
165 if let Some(raw) = request.param("at") {
166 let wanted = match requested_position(raw) {
167 Ok(position) => position,
168 Err(bad) => {
169 return Ok(respond(
170 stream,
171 400,
172 "Bad Request",
173 &[],
174 &format!("`{bad}` is not a position\n"),
175 )
176 .await?);
177 }
178 };
179
180 if through.is_none_or(|reached| reached < wanted.get()) {
181 return Ok(respond(
182 stream,
183 202,
184 "Accepted",
185 &[("X-Happenstance-Checkpoint", checkpoint)],
186 "the read model has not reached that position yet\n",
187 )
188 .await?);
189 }
190 }
191
192 let app = open_configured(&state.path)?;
193 let mut body = String::new();
194 for (seat, patron) in seat_rows(&app)? {
195 // Writing into a `String` cannot fail; the `Result` is discarded rather
196 // than `unwrap`ped so this server carries no panic path a request could
197 // reach even in principle.
198 let _ = writeln!(body, "{seat} {patron}");
199 }
200
201 Ok(respond(
202 stream,
203 200,
204 "OK",
205 &[("X-Happenstance-Checkpoint", checkpoint)],
206 &body,
207 )
208 .await?)
209}836fn settle(
837 result: core::result::Result<CommandOutcome, CommandError<SqliteEventStoreError, Refusal>>,
838) -> Result<Outcome> {
839 match result {
840 Ok(CommandOutcome::Committed(committed)) => Ok(Outcome::Applied {
841 position: committed.position.get(),
842 attempts: committed.attempts,
843 }),
844
845 // **This example refuses instead of deciding nothing, and the arm is
846 // here to say that is a choice.** `CommandOutcome::Nothing` and
847 // `Refusal::AlreadyApplied` both mean *this delivery was already
848 // handled*; they differ in what they can carry. `Nothing` carries no
849 // payload, and the whole point of the idempotent path below is
850 // reporting `landed` — what the *first* delivery did — which a handler
851 // that returned an empty `Vec` would have thrown away before this
852 // function saw it.
853 //
854 // So reaching this arm means a handler returned no events on a path
855 // that was supposed to refuse, and it is reported rather than folded
856 // into `Applied` with a fabricated position. Deciding nothing is the
857 // right shape when there is nothing to say; here there is.
858 Ok(CommandOutcome::Nothing) => bail!(
859 "a handler decided no events: this example's idempotent path refuses with `AlreadyApplied` so that it can report what the first delivery landed, and an empty decision has nowhere to put it"
860 ),
861
862 Err(CommandError::Refused(Refusal::AlreadyApplied { landed })) => {
863 Ok(Outcome::Replayed { landed })
864 }
865 Err(CommandError::Refused(refusal)) => Err(refusal.into()),
866 Err(other) => Err(other.into()),
867 }
868}
869
870// ---------------------------------------------------------------------------
871// Reading
872// ---------------------------------------------------------------------------
873
874/// Prints the query items a boundary derives, one per line.
875///
876/// Generic over `Boundary`, which is what a tuple of decision models becomes.
877/// The trait is sealed, so this signature can consume one and no crate outside
878/// `happenstance` can add a third kind of implementor to surprise it.
879fn print_boundary<B: Boundary>(boundary: &B) -> Result<()> {
880 let query = boundary.query()?;
881
882 match query.items() {
883 Some(items) => {
884 for item in items {
885 let types: Vec<&str> = item.types().iter().map(EventType::as_str).collect();
886 println!(" {} where {:?}", types.join(" | "), item.tags());
887 }
888 }
889 // Unreachable for a well-formed model, and spelled rather than
890 // `unwrap`ped: `Query::All` is what a boundary constraining neither
891 // types nor tags would produce, and an empty `EVENT_TYPES` is already
892 // a compile error.
893 None => println!(" the whole log"),
894 }
895
896 Ok(())
897}
898
899/// The position of the last event in the store, or 0 if there is none.
900async fn head(events: &SqliteEventStore) -> Result<u64> {
901 Ok(events.head().await?.map_or(0, SequencePosition::get))
902}
903
904/// Prints every event in the store, in the order the store assigned.
905async fn print_log(events: &SqliteEventStore) -> Result<()> {
906 let log = collect(events.read(&Query::all(), ReadOptions::new())).await?;
907
908 for event in log {
909 println!(
910 " {:>3} {:<15} {:?}",
911 event.position.get(),
912 event.event_type().as_str(),
913 event.tags()
914 );
915 }
916
917 Ok(())
918}Sourcepub const fn next(self) -> Option<Self>
pub const fn next(self) -> Option<Self>
The next position, or None on overflow.
This is the resume idiom. A consumer that has processed up to
checkpoint resumes with ReadOptions::from(checkpoint.next()?), and
that is sound on a store with gaps: from is a threshold rather than a
seek, so if nothing occupies checkpoint + 1 the read yields the next
event above it. This is not the caller doing arithmetic on an opaque
ordering key — it is the one method on this type whose whole purpose is
to advance past a position without the caller knowing what positions
mean.
Do not read Some as a promise that an event exists there, or that the
next append will land there. The specification permits gaps everywhere.
Trait Implementations§
Source§impl Clone for SequencePosition
impl Clone for SequencePosition
impl Copy for SequencePosition
Source§impl Debug for SequencePosition
impl Debug for SequencePosition
Source§impl<'de> Deserialize<'de> for SequencePosition
Available on crate feature serde only.
impl<'de> Deserialize<'de> for SequencePosition
serde only.Source§fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>
Source§impl Display for SequencePosition
impl Display for SequencePosition
impl Eq for SequencePosition
Source§impl From<SequencePosition> for u64
impl From<SequencePosition> for u64
Source§fn from(position: SequencePosition) -> Self
fn from(position: SequencePosition) -> Self
Source§impl Hash for SequencePosition
impl Hash for SequencePosition
Source§impl Ord for SequencePosition
impl Ord for SequencePosition
1.21.0 (const: unstable) · Source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
1.21.0 (const: unstable) · Source§fn min(self, other: Self) -> Selfwhere
Self: Sized,
fn min(self, other: Self) -> Selfwhere
Self: Sized,
Source§impl PartialEq for SequencePosition
impl PartialEq for SequencePosition
Source§impl PartialOrd for SequencePosition
impl PartialOrd for SequencePosition
Source§impl Serialize for SequencePosition
Available on crate feature serde only.
impl Serialize for SequencePosition
serde only.