window_machines 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9587883520f31642bd8ef66526e42dfe82c863f19d5eb282d91dd01d078fe22c
+  data.tar.gz: c3d6d27cfc1557e9b1adf5675f5b67f6a1a2d60a201988964840d9c402962577
+SHA512:
+  metadata.gz: b861a7b54a3e228649b94e4c21679edab4a23bfe0d0dd0d8969c04e7284f3ad5c782931588e6577b7574813374fe715d476b574af239eae82544f046780d896a
+  data.tar.gz: b11786fd6ce936ee32627894fcff863aa52190ce57cce53ae6442cc5919cb196d3972c84fa0953a9f3d5b30000c9be01f2ab8b22ad8123660b9df849639c93fa

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.1.4](https://github.com/seuros/window_machines/compare/window_machines/v0.1.3...window_machines/v0.1.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([b8098d7](https://github.com/seuros/window_machines/commit/b8098d7d280dfd4e48ba7ade3a72b7f891853ec4))
+
+## [0.1.3](https://github.com/seuros/window_machines/compare/window_machines/v0.1.2...window_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([db7ff81](https://github.com/seuros/window_machines/commit/db7ff817e11a2448c17640631c2f8a6a254447a3))
+
+## [0.1.2](https://github.com/seuros/window_machines/compare/window_machines/v0.1.1...window_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* cross builds no longer compile for the host ([ca5ad94](https://github.com/seuros/window_machines/commit/ca5ad94ba196793f6366a9a5025903bd5bd22c51))
+
+## [0.1.1](https://github.com/seuros/window_machines/compare/window_machines-v0.1.0...window_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([3bd753e](https://github.com/seuros/window_machines/commit/3bd753ec5ae5890e4e54272e5df4523c9d685d4b))

data/Cargo.toml

@@ -0,0 +1,21 @@
+[workspace]
+members = ["ext/window_machines_native/core", "ext/window_machines_native/ffi"]
+default-members = ["ext/window_machines_native/core"]
+resolver = "3"
+[workspace.package]
+edition = "2024"
+rust-version = "1.99"
+license = "MIT"
+[workspace.dependencies]
+window-machines = { path = "ext/window_machines_native/core" }
+magnus = { version = "0.9.3", default-features = false }
+rb-sys = { version = "0.9.130", default-features = false, features = ["stable-api-compiled-fallback"] }
+[workspace.lints.rust]
+unsafe_code = "deny"
+unused_must_use = "warn"
+[workspace.lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+unwrap_used = "deny"
+expect_used = "deny"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,198 @@
+# WindowMachines
+
+> Bucket events by when they happened, not by when they finally showed up. 🔭
+
+Event-time windows for Ruby. Give it a timestamp and it tells you which tumbling or sliding bucket the event belongs in. Give it a `Watermark` and it tells you when a bucket is safe to close. Give it a `Sessions` tracker and it groups bursts of activity, merging two bursts into one when a late arrival turns out to bridge the gap.
+
+## Quick Start
+
+```bash
+gem 'window_machines'
+```
+
+```ruby
+# Every event lands in a ten-minute bucket, keyed by its own timestamp.
+WindowMachines.tumbling(event.at, 600)      # => [start, end] of its bucket
+
+# Nothing gets reported until the watermark says the bucket is done.
+watermark = WindowMachines::Watermark.new
+watermark.advance(latest_timestamp_seen)
+watermark.closes?(start, finish, 120)       # => true once start..finish is two minutes behind
+
+# Activity bursts, split by five minutes of silence, merged if something fills the gap.
+sessions = WindowMachines::Sessions.new(300)
+sessions.insert(event.at)                   # => [first, last] of the session it joined
+sessions.advance_watermark(latest_timestamp_seen)
+sessions.take_closed                        # => the oldest finished session, or nil
+```
+
+Timestamps are Integers in whatever unit you pick. Seconds, milliseconds, ticks. The gem never looks at a clock.
+
+## A Message to the Resistance
+
+So you built the signups-per-ten-minutes chart. You bucket each event by `Time.now` as it comes off the queue, you flush the bucket when the clock crosses the boundary, product loves it.
+
+Then the mobile app ships an offline queue. A user signs up on a plane at 14:03, the phone syncs at 16:40, and your chart puts the signup in the 16:40 bucket. The 14:00 bucket was flushed two hours ago and will never be corrected. Nobody notices until finance reconciles the month and the numbers don't add up.
+
+The event knew when it happened. Your pipeline threw that away and used arrival time instead, because arrival time is what the clock on the wall gives you for free.
+
+This gem is the other way around. The event's own timestamp decides the bucket. A watermark you advance decides when a bucket has waited long enough for stragglers. Late arrivals land in the right bucket or get rejected loudly, never quietly misfiled.
+
+## Chapter 1: Stardate 2025.186, the AMS Akidau
+
+> **AMS Akidau**, NCC-4219, *Akidau*-class survey vessel.
+> The order telemetry arrives is not the order the stars emitted it.
+
+Light from a near star reaches the survey deck in minutes. Light from a far one takes years. The deck doesn't log a supernova under the day the photons hit the sensor. It logs it under the day it happened, and it waits a stated grace period before declaring any day's catalogue final.
+
+Somewhere in the chart room, a cadet files:
+
+```ruby
+def bucket_for(event)
+  (Time.now.to_i / 600) * 600   # close enough
+end
+```
+
+"That," says the survey officer, "is how a supernova ends up catalogued two years late."
+
+## The Flight Plan
+
+Each window moves through three states as the watermark catches up with it:
+
+```mermaid
+stateDiagram-v2
+    [*] --> open
+    open --> open: event with timestamp inside the window
+    open --> closable: watermark reaches window end plus allowed lateness
+    closable --> reported: you emit it and take_closed hands it over
+    reported --> [*]
+    open --> rejected: insert at or below the watermark
+    rejected --> [*]
+```
+
+And the signup that flew in from a plane:
+
+```mermaid
+sequenceDiagram
+    participant Q as Queue
+    participant W as Watermark
+    participant B as Bucket 14:00-14:10
+
+    Q->>B: signup at 14:03 (arrived 16:40)
+    Note over B: tumbling(14:03, 600) picks this bucket
+    Q->>W: advance(16:40)
+    W-->>B: closes?(14:00, 14:10, 120) => true
+    Note over B: safe to report, 14:03 included
+```
+
+With the grace period set to two minutes, a bucket closes once the watermark is two minutes past its end. Any event that still claims to belong in a closed bucket is refused instead of miscounted.
+
+## How Windows Work
+
+### Tumbling
+
+Fixed-size, back-to-back buckets. A timestamp belongs to exactly one.
+
+```ruby
+WindowMachines.tumbling(12, 10)   # => [10, 20]
+WindowMachines.tumbling(19, 10)   # => [10, 20]
+WindowMachines.tumbling(20, 10)   # => [20, 30]
+```
+
+Windows are half-open. The start is inside, the end is not, so 20 begins the next bucket.
+
+### Sliding
+
+Overlapping buckets of one width, started every `slide`. A timestamp can sit in several at once. You get them newest first.
+
+```ruby
+WindowMachines.sliding(12, 10, 5)   # => [[10, 20], [5, 15]]
+WindowMachines.sliding(7, 10, 5)    # => [[5, 15], [0, 10]]
+```
+
+A slide wider than the width leaves holes. A timestamp that falls into a hole gets an empty list, not a guess:
+
+```ruby
+WindowMachines.sliding(12, 1, 5)    # => []
+```
+
+### Watermarks
+
+A watermark is your claim that nothing older than this will still turn up. You advance it. It never moves backwards.
+
+```ruby
+watermark = WindowMachines::Watermark.new
+watermark.value           # => nil, nothing seen yet
+watermark.advance(22)     # => true
+watermark.advance(9)      # => false, ignored
+watermark.value           # => 22
+```
+
+`closes?` answers whether a window has waited long enough. It takes the window plus how much lateness you're willing to absorb:
+
+```ruby
+watermark.closes?(10, 20, 2)   # => true, 20 + 2 is not past 22
+watermark.closes?(10, 20, 3)   # => false, give it one more tick
+watermark.closes?(20, 30, 0)   # => false, still open
+```
+
+### Sessions
+
+Sessions have no fixed size. A session is a run of events where no two neighbours are more than `gap` apart. Insert returns the span of whichever session the event ended up in.
+
+```ruby
+sessions = WindowMachines::Sessions.new(5)
+sessions.insert(10)   # => [10, 10], a new session
+sessions.insert(15)   # => [10, 15], five apart, still one session
+sessions.insert(30)   # => [30, 30], too far, a second session
+sessions.insert(21)   # => [21, 21], nine from 30, a third
+```
+
+Then the late one shows up:
+
+```ruby
+sessions.insert(26)   # => [21, 30], bridges the gap and merges two sessions into one
+```
+
+A session is finished once the watermark is a full `gap` past its last event. `take_closed` hands you the oldest finished session and forgets it. Call it until it returns `nil`.
+
+```ruby
+sessions.advance_watermark(25)
+sessions.take_closed      # => [10, 15], 15 + 5 is behind 25
+sessions.take_closed      # => nil, [21, 30] is still open
+
+sessions.advance_watermark(40)
+sessions.take_closed      # => [21, 30]
+```
+
+Anything at or below the watermark is late by definition and raises, leaving the sessions untouched:
+
+```ruby
+sessions.insert(40)   # => raises ArgumentError
+```
+
+## The Rules of the Survey
+
+- **Everything is an Integer** in `0..2**64-1`. Floats, strings, and anything else raise `TypeError`. Negative or oversized values raise `RangeError`.
+- **Zero widths, slides, and gaps are rejected** with `ArgumentError`. A bucket of size zero holds nothing.
+- **Sliding is capped at 32 windows per timestamp.** A width-to-slide ratio that would produce more raises `RangeError` rather than truncating the list.
+- **Sessions hold at most 32 open sessions at once.** A 33rd raises `RangeError` and nothing is dropped to make room. Close some first.
+- **Late inserts raise.** An event at or below the sessions watermark is refused, not silently folded into something.
+- **Frozen means frozen.** `freeze` a watermark or a sessions tracker and every mutation raises `FrozenError`.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "I'll just add a small delay before flushing. Late events are rare."
+### Reality: Late is a distribution, not an edge case.
+
+Mobile sync, retried webhooks, a consumer that fell behind for an hour. A fixed delay picks one point on that curve and misfiles everything past it. A watermark you advance from the data itself moves with the curve, and `closes?` with explicit lateness makes the trade-off a number you chose, not one you guessed.
+
+## What's Yours
+
+The gem decides boundaries. It never stores a payload. Keep your own counts or rows per `[start, end]` pair, add to them when an event is bucketed, and emit them when `closes?` says so or `take_closed` returns a span. Advancing the watermark is also your call. Drive it from the timestamps you've actually seen, with whatever lag your sources deserve.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: The signup happened at 14:03. The phone only admitted it at 16:40.**

data/ext/window_machines_native/core/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.2.2](https://github.com/seuros/window_machines/compare/window-machines-v0.2.1...window-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([b8098d7](https://github.com/seuros/window_machines/commit/b8098d7d280dfd4e48ba7ade3a72b7f891853ec4))
+
+## [0.2.1](https://github.com/seuros/window_machines/compare/window-machines-v0.2.0...window-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([db7ff81](https://github.com/seuros/window_machines/commit/db7ff817e11a2448c17640631c2f8a6a254447a3))
+
+## [0.2.0](https://github.com/seuros/window_machines/compare/window-machines-v0.1.0...window-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([3bd753e](https://github.com/seuros/window_machines/commit/3bd753ec5ae5890e4e54272e5df4523c9d685d4b))

data/ext/window_machines_native/core/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "window-machines"
+version = "0.2.2"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Bounded event-time windows, watermarks, and session merging"
+readme = "README.md"
+exclude = ["src/**/tests.rs", "tests/"]
+keywords = ["windowing", "event-time", "watermark", "sessions", "no-std"]
+categories = ["no-std", "algorithms"]
+[lints]
+workspace = true

data/ext/window_machines_native/core/README.md

@@ -0,0 +1,22 @@
+# window-machines
+
+> **AMS Akidau**, NCC-4219, *Akidau*-class survey vessel.
+
+Engine-room flight manual: divide observation time into bounded survey windows.
+
+Allocation-free `no_std` window boundaries and one-key bounded session tracking.
+All timestamps and widths use one caller-selected unsigned unit and origin.
+Tumbling/sliding windows are aligned to zero and half-open `[start, end)`.
+Sliding results are newest-start-first; too-small output capacity rejects rather
+than silently truncating. Overflowing boundaries reject.
+
+Watermarks never regress. A window closes when watermark reaches its end plus
+allowed lateness; arithmetic overflow means it cannot yet close.
+
+Sessions merge events whose inactivity gaps are **at most** the configured gap,
+including out-of-order bridging events. Events at/below the current watermark
+are late and rejected; session allowed lateness is zero in this version. Advancing
+a watermark does not discard sessions: explicitly drain `take_closed()`.
+Full tables reject events that cannot merge. Callers retain aggregation payloads
+and apply the same merges; the core stores boundaries only. Multi-key indexing,
+retractions, and distributed watermark coordination are not implemented.

data/ext/window_machines_native/core/src/lib.rs

@@ -0,0 +1,85 @@
+#![no_std]
+#![doc = include_str!("../README.md")]
+use core::num::NonZeroU64;
+
+mod sessions;
+pub use sessions::{Insert, Session, Sessions};
+
+/// Half-open event-time interval.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Window {
+    /// Inclusive start.
+    pub start: u64,
+    /// Exclusive end.
+    pub end: u64,
+}
+
+/// Zero-aligned tumbling window containing this event.
+#[must_use]
+pub const fn tumbling(timestamp: u64, width: NonZeroU64) -> Option<Window> {
+    let start = timestamp - timestamp % width.get();
+    match start.checked_add(width.get()) {
+        Some(end) => Some(Window { start, end }),
+        None => None,
+    }
+}
+
+/// All nonnegative zero-aligned sliding windows containing this event.
+#[must_use]
+pub fn sliding<const N: usize>(
+    timestamp: u64,
+    size: NonZeroU64,
+    slide: NonZeroU64,
+) -> Option<[Option<Window>; N]> {
+    let mut result = [None; N];
+    let mut start = timestamp - timestamp % slide.get();
+    let mut count = 0;
+    loop {
+        let end = start.checked_add(size.get())?;
+        if end <= timestamp {
+            break;
+        }
+        if count == N {
+            return None;
+        }
+        result[count] = Some(Window { start, end });
+        count += 1;
+        let Some(previous) = start.checked_sub(slide.get()) else {
+            break;
+        };
+        start = previous;
+    }
+    Some(result)
+}
+
+/// Monotonic event-time progress, not a wall clock or consensus watermark.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub struct Watermark {
+    value: Option<u64>,
+}
+impl Watermark {
+    /// Advance or repeat progress; reject backwards observations.
+    #[must_use]
+    pub fn advance(&mut self, value: u64) -> bool {
+        if self.value.is_some_and(|old| value < old) {
+            return false;
+        }
+        self.value = Some(value);
+        true
+    }
+    /// Last observation, or `None` before initialization.
+    #[must_use]
+    pub const fn value(self) -> Option<u64> {
+        self.value
+    }
+    /// Whether event-time progress closes this interval plus allowed lateness.
+    #[must_use]
+    pub fn closes(self, window: Window, allowed_lateness: u64) -> bool {
+        window
+            .end
+            .checked_add(allowed_lateness)
+            .is_some_and(|end| self.value.is_some_and(|value| value >= end))
+    }
+}
+#[cfg(test)]
+mod tests;

data/ext/window_machines_native/core/src/sessions.rs

@@ -0,0 +1,129 @@
+use crate::Watermark;
+use core::num::NonZeroU64;
+
+/// Boundaries of a session; both endpoints are actual included event timestamps.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Session {
+    /// Earliest event.
+    pub first: u64,
+    /// Latest event.
+    pub last: u64,
+}
+
+/// Session event admission.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum Insert {
+    /// New or merged boundaries; adapters must merge overlapping payloads too.
+    Accepted(Session),
+    /// Event is at/below the current watermark.
+    Late,
+    /// No free slot and no existing session could absorb the event.
+    Full,
+    /// Inactivity endpoint overflowed.
+    Overflow,
+}
+
+/// Bounded sessions for one logical event key.
+#[derive(Debug)]
+pub struct Sessions<const N: usize> {
+    entries: [Option<Session>; N],
+    gap: NonZeroU64,
+    watermark: Watermark,
+}
+impl<const N: usize> Sessions<N> {
+    /// Construct an empty one-key session tracker.
+    #[must_use]
+    pub fn new(gap: NonZeroU64) -> Self {
+        Self {
+            entries: [None; N],
+            gap,
+            watermark: Watermark::default(),
+        }
+    }
+
+    /// Merge an event atomically, including bridges across multiple sessions.
+    #[must_use]
+    pub fn insert(&mut self, timestamp: u64) -> Insert {
+        if self
+            .watermark
+            .value()
+            .is_some_and(|value| timestamp <= value)
+        {
+            return Insert::Late;
+        }
+        if timestamp.checked_add(self.gap.get()).is_none() {
+            return Insert::Overflow;
+        }
+        let mut candidate = Session {
+            first: timestamp,
+            last: timestamp,
+        };
+        let mut merged = [false; N];
+        // Fixed point handles any slot order and transitive bridges.
+        for _ in 0..N {
+            let mut changed = false;
+            for (index, session) in self.entries.iter().enumerate() {
+                let Some(session) = session else {
+                    continue;
+                };
+                if !merged[index]
+                    && u128::from(candidate.first)
+                        <= u128::from(session.last) + u128::from(self.gap.get())
+                    && u128::from(session.first)
+                        <= u128::from(candidate.last) + u128::from(self.gap.get())
+                {
+                    merged[index] = true;
+                    candidate.first = candidate.first.min(session.first);
+                    candidate.last = candidate.last.max(session.last);
+                    changed = true;
+                }
+            }
+            if !changed {
+                break;
+            }
+        }
+        let Some(slot) = merged
+            .iter()
+            .position(|merged| *merged)
+            .or_else(|| self.entries.iter().position(Option::is_none))
+        else {
+            return Insert::Full;
+        };
+        for (index, merged) in merged.into_iter().enumerate() {
+            if merged {
+                self.entries[index] = None;
+            }
+        }
+        self.entries[slot] = Some(candidate);
+        Insert::Accepted(candidate)
+    }
+
+    /// Advance event-time progress, without silently deleting closed sessions.
+    #[must_use]
+    pub fn advance_watermark(&mut self, value: u64) -> bool {
+        self.watermark.advance(value)
+    }
+
+    /// Drain the earliest closed session; payload emission remains the caller's job.
+    pub fn take_closed(&mut self) -> Option<Session> {
+        let value = self.watermark.value()?;
+        let index = self
+            .entries
+            .iter()
+            .enumerate()
+            .filter_map(|(index, session)| {
+                session
+                    .filter(|session| {
+                        session
+                            .last
+                            .checked_add(self.gap.get())
+                            .is_some_and(|end| value >= end)
+                    })
+                    .map(|session| (index, session.first))
+            })
+            .min_by_key(|&(_, first)| first)
+            .map(|(index, _)| index)?;
+        self.entries[index].take()
+    }
+}

data/ext/window_machines_native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ffi/extconf'

data/ext/window_machines_native/ffi/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "window_machines_native"
+version = "0.1.3"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+test = false
+doctest = false
+
+[dependencies]
+window-machines.workspace = true
+magnus.workspace = true
+rb-sys.workspace = true
+
+[lints]
+workspace = true

data/ext/window_machines_native/ffi/extconf.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'pathname'
+require 'rb_sys/mkmf'
+create_rust_makefile('window_machines_native/window_machines_native') do |extension|
+  extension.ext_dir = Pathname(__dir__).relative_path_from(Pathname(Dir.pwd)).to_s
+  extension.profile = ENV.fetch('RB_SYS_CARGO_PROFILE', :release).to_sym
+end
+# Installed source gems enter via the parent extconf, unlike rake-compiler.
+makefile = File.join(Dir.pwd, 'Makefile')
+File.write(makefile, File.read(makefile).gsub(
+  /^RB_SYS_CARGO_MANIFEST_DIR \?=.*$/,
+  "RB_SYS_CARGO_MANIFEST_DIR ?= #{File.expand_path(__dir__)}"
+))

data/ext/window_machines_native/ffi/src/init.rs

@@ -0,0 +1,10 @@
+use magnus::{Error, Ruby, function, prelude::*};
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("WindowMachines")?;
+    module.define_singleton_method("tumbling", function!(crate::tumbling, 2))?;
+    module.define_singleton_method("sliding", function!(crate::sliding, 3))?;
+    crate::watermark::define(ruby, module)?;
+    crate::sessions::define(ruby, module)
+}

data/ext/window_machines_native/ffi/src/lib.rs

@@ -0,0 +1,46 @@
+//! Thin event-time boundary adapters; no Ruby payloads are retained.
+mod init;
+mod sessions;
+mod watermark;
+
+use std::num::NonZeroU64;
+
+use magnus::{Error, Integer, RArray, Ruby, TryConvert, Value};
+
+#[derive(Clone, Copy)]
+struct Tick(u64);
+
+impl TryConvert for Tick {
+    fn try_convert(value: Value) -> Result<Self, Error> {
+        if Integer::from_value(value).is_none() {
+            return Err(Error::new(
+                Ruby::get_with(value).exception_type_error(),
+                "time must be an Integer in 0..2**64",
+            ));
+        }
+        u64::try_convert(value).map(Self)
+    }
+}
+
+fn positive(ruby: &Ruby, value: Tick) -> Result<NonZeroU64, Error> {
+    NonZeroU64::new(value.0)
+        .ok_or_else(|| Error::new(ruby.exception_arg_error(), "width/gap must be positive"))
+}
+
+fn tumbling(ruby: &Ruby, time: Tick, width: Tick) -> Result<(u64, u64), Error> {
+    let window = window_machines::tumbling(time.0, positive(ruby, width)?)
+        .ok_or_else(|| Error::new(ruby.exception_range_error(), "window endpoint overflow"))?;
+    Ok((window.start, window.end))
+}
+
+fn sliding(ruby: &Ruby, time: Tick, width: Tick, slide: Tick) -> Result<RArray, Error> {
+    let windows =
+        window_machines::sliding::<32>(time.0, positive(ruby, width)?, positive(ruby, slide)?)
+            .ok_or_else(|| {
+                Error::new(
+                    ruby.exception_range_error(),
+                    "endpoint overflow or more than 32 sliding windows",
+                )
+            })?;
+    Ok(ruby.ary_from_iter(windows.into_iter().flatten().map(|w| (w.start, w.end))))
+}

data/ext/window_machines_native/ffi/src/sessions.rs

@@ -0,0 +1,55 @@
+use std::cell::RefCell;
+
+use magnus::{Error, RArray, RModule, Ruby, function, method, prelude::*, typed_data::Obj};
+use window_machines::{Insert, Sessions};
+
+use crate::{Tick, positive};
+
+#[magnus::wrap(class = "WindowMachines::Sessions", free_immediately, size)]
+struct Wrapper(RefCell<Sessions<32>>);
+
+impl Wrapper {
+    fn new(ruby: &Ruby, gap: Tick) -> Result<Self, Error> {
+        Ok(Self(RefCell::new(Sessions::new(positive(ruby, gap)?))))
+    }
+
+    fn insert(ruby: &Ruby, this: Obj<Self>, time: Tick) -> Result<RArray, Error> {
+        this.check_frozen()?;
+        let result = this.0.borrow_mut().insert(time.0);
+        // No Ruby allocation while a RefCell guard is alive.
+        match result {
+            Insert::Accepted(session) => Ok(ruby.ary_from_iter([session.first, session.last])),
+            Insert::Late => Err(Error::new(
+                ruby.exception_arg_error(),
+                "event at/below watermark",
+            )),
+            Insert::Full => Err(Error::new(
+                ruby.exception_range_error(),
+                "32 session capacity reached",
+            )),
+            _ => Err(Error::new(
+                ruby.exception_range_error(),
+                "session endpoint overflow",
+            )),
+        }
+    }
+
+    fn advance(this: Obj<Self>, time: Tick) -> Result<bool, Error> {
+        this.check_frozen()?;
+        Ok(this.0.borrow_mut().advance_watermark(time.0))
+    }
+
+    fn take_closed(this: Obj<Self>) -> Result<Option<(u64, u64)>, Error> {
+        this.check_frozen()?;
+        let session = this.0.borrow_mut().take_closed();
+        Ok(session.map(|s| (s.first, s.last)))
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("Sessions", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, 1))?;
+    class.define_method("insert", method!(Wrapper::insert, 1))?;
+    class.define_method("advance_watermark", method!(Wrapper::advance, 1))?;
+    class.define_method("take_closed", method!(Wrapper::take_closed, 0))
+}

data/ext/window_machines_native/ffi/src/watermark.rs

@@ -0,0 +1,54 @@
+use std::cell::RefCell;
+
+use magnus::{Error, RModule, Ruby, function, method, prelude::*, typed_data::Obj};
+use window_machines::{Watermark, Window};
+
+use crate::Tick;
+
+#[magnus::wrap(class = "WindowMachines::Watermark", free_immediately, size)]
+struct Wrapper(RefCell<Watermark>);
+
+impl Wrapper {
+    fn new() -> Self {
+        Self(RefCell::new(Watermark::default()))
+    }
+
+    fn advance(this: Obj<Self>, time: Tick) -> Result<bool, Error> {
+        this.check_frozen()?;
+        Ok(this.0.borrow_mut().advance(time.0))
+    }
+
+    fn value(&self) -> Option<u64> {
+        self.0.borrow().value()
+    }
+
+    fn closes(
+        ruby: &Ruby,
+        this: &Self,
+        start: Tick,
+        end: Tick,
+        lateness: Tick,
+    ) -> Result<bool, Error> {
+        if start.0 >= end.0 || end.0.checked_add(lateness.0).is_none() {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "invalid interval/lateness",
+            ));
+        }
+        Ok(this.0.borrow().closes(
+            Window {
+                start: start.0,
+                end: end.0,
+            },
+            lateness.0,
+        ))
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let class = module.define_class("Watermark", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Wrapper::new, 0))?;
+    class.define_method("advance", method!(Wrapper::advance, 1))?;
+    class.define_method("value", method!(Wrapper::value, 0))?;
+    class.define_method("closes?", method!(Wrapper::closes, 3))
+}

data/lib/window_machines/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WindowMachines
+  VERSION = '0.1.4'
+end

data/lib/window_machines.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'window_machines/version'
+require 'window_machines_native/window_machines_native'

data/sig/window_machines.rbs

@@ -0,0 +1,17 @@
+module WindowMachines
+  VERSION: String
+  def self.tumbling: (Integer timestamp, Integer width) -> [Integer, Integer]
+  def self.sliding: (Integer timestamp, Integer width, Integer slide) -> Array[[Integer, Integer]]
+  class Watermark
+    def self.new: () -> instance
+    def advance: (Integer value) -> bool
+    def value: () -> Integer?
+    def closes?: (Integer start, Integer end, Integer lateness) -> bool
+  end
+  class Sessions
+    def self.new: (Integer gap) -> instance
+    def insert: (Integer timestamp) -> [Integer, Integer]
+    def advance_watermark: (Integer value) -> bool
+    def take_closed: () -> [Integer, Integer]?
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: window_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+description: Initial allocation-free window policy core and thin native Ruby binding.
+  Caller owns payloads, clocks, and execution.
+email:
+- oss@seuros.com
+executables: []
+extensions:
+- ext/window_machines_native/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- ext/window_machines_native/core/CHANGELOG.md
+- ext/window_machines_native/core/Cargo.toml
+- ext/window_machines_native/core/README.md
+- ext/window_machines_native/core/src/lib.rs
+- ext/window_machines_native/core/src/sessions.rs
+- ext/window_machines_native/extconf.rb
+- ext/window_machines_native/ffi/Cargo.toml
+- ext/window_machines_native/ffi/extconf.rb
+- ext/window_machines_native/ffi/src/init.rs
+- ext/window_machines_native/ffi/src/lib.rs
+- ext/window_machines_native/ffi/src/sessions.rs
+- ext/window_machines_native/ffi/src/watermark.rs
+- lib/window_machines.rb
+- lib/window_machines/version.rb
+- sig/window_machines.rbs
+homepage: https://github.com/seuros/window_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/window_machines
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: window_machines_native
+  cargo_manifest_path: ext/window_machines_native/ffi/Cargo.toml
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Native event-time window boundaries for Ruby
+test_files: []