add examples

Author: GaspardKirira

examples/README.md

@@ -0,0 +1,22 @@
+# Sync examples
+This folder is a living playground for Vix.cpp offline-first sync.
+
+Run with your usual workflow (example):
+
+- vix run examples/sync/outbox_smoke.cpp
+- vix run examples/sync/outbox_permanent_fail.cpp
+- vix run examples/sync/inflight_timeout.cpp
+
+Each example writes its own local outbox file under a .vix_example_sync_* folder.
+
+Run:
+
+- vix run examples/sync/vix_sync_showcase.cpp
+
+It creates local files under:
+
+- .vix_example_sync_smoke/
+- .vix_example_sync_offline/
+- .vix_example_sync_retry/
+- .vix_example_sync_permfail/
+- .vix_example_sync_inflight/

examples/fake_http_transport.cpp

@@ -0,0 +1,88 @@
+/**
+ *
+ *  @file fake_http_transport.hpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ *
+ */
+#ifndef VIX_EXAMPLES_SYNC_FAKE_HTTP_TRANSPORT_HPP
+#define VIX_EXAMPLES_SYNC_FAKE_HTTP_TRANSPORT_HPP
+
+#include <string>
+#include <unordered_map>
+#include <utility>
+
+#include <vix/sync/engine/SyncWorker.hpp>
+
+namespace vix::sync::engine
+{
+  // Fake transport: rule-based outcomes by operation kind/target/id
+  class FakeHttpTransport final : public ISyncTransport
+  {
+  public:
+    struct Rule
+    {
+      bool ok{true};
+      bool retryable{true};
+      std::string error{"simulated failure"};
+    };
+
+    void setDefault(Rule r) { def_ = std::move(r); }
+
+    void setRuleForKind(std::string kind, Rule r)
+    {
+      by_kind_[std::move(kind)] = std::move(r);
+    }
+
+    void setRuleForTarget(std::string target, Rule r)
+    {
+      by_target_[std::move(target)] = std::move(r);
+    }
+
+    std::size_t callCount() const noexcept { return calls_; }
+
+    SendResult send(const vix::sync::Operation &op) override
+    {
+      ++calls_;
+
+      if (auto it = by_target_.find(op.target); it != by_target_.end())
+      {
+        return toResult(it->second);
+      }
+
+      if (auto it = by_kind_.find(op.kind); it != by_kind_.end())
+      {
+        return toResult(it->second);
+      }
+
+      return toResult(def_);
+    }
+
+  private:
+    static SendResult toResult(const Rule &r)
+    {
+      SendResult res;
+      res.ok = r.ok;
+      res.retryable = r.retryable;
+      res.error = r.ok ? "" : r.error;
+      return res;
+    }
+
+  private:
+    Rule def_{};
+    std::unordered_map<std::string, Rule> by_kind_;
+    std::unordered_map<std::string, Rule> by_target_;
+    std::size_t calls_{0};
+  };
+
+} // namespace vix::sync::engine
+
+#endif

examples/fake_transport.hpp

@@ -0,0 +1,76 @@
+/**
+ *
+ *  @file fake_transport.hpp
+ *  @author Gaspard Kirira
+ *
+ *  Vix.cpp - Sync examples
+ *
+ */
+#ifndef VIX_EXAMPLES_SYNC_FAKE_TRANSPORT_HPP
+#define VIX_EXAMPLES_SYNC_FAKE_TRANSPORT_HPP
+
+#include <string>
+#include <unordered_map>
+#include <utility>
+
+#include <vix/sync/engine/SyncWorker.hpp>
+
+namespace vix::sync::engine
+{
+  class FakeTransport final : public ISyncTransport
+  {
+  public:
+    struct Rule
+    {
+      bool ok{true};
+      bool retryable{true};
+      std::string error{"simulated failure"};
+    };
+
+    void setDefault(Rule r) { def_ = std::move(r); }
+
+    void setRuleForKind(std::string kind, Rule r)
+    {
+      by_kind_[std::move(kind)] = std::move(r);
+    }
+
+    void setRuleForTarget(std::string target, Rule r)
+    {
+      by_target_[std::move(target)] = std::move(r);
+    }
+
+    std::size_t callCount() const noexcept { return calls_; }
+
+    SendResult send(const vix::sync::Operation &op) override
+    {
+      ++calls_;
+
+      if (auto it = by_target_.find(op.target); it != by_target_.end())
+        return toResult(it->second);
+
+      if (auto it = by_kind_.find(op.kind); it != by_kind_.end())
+        return toResult(it->second);
+
+      return toResult(def_);
+    }
+
+  private:
+    static SendResult toResult(const Rule &r)
+    {
+      SendResult res;
+      res.ok = r.ok;
+      res.retryable = r.retryable;
+      res.error = r.ok ? "" : r.error;
+      return res;
+    }
+
+  private:
+    Rule def_{};
+    std::unordered_map<std::string, Rule> by_kind_;
+    std::unordered_map<std::string, Rule> by_target_;
+    std::size_t calls_{0};
+  };
+
+} // namespace vix::sync::engine
+
+#endif

examples/inflight_timeout.cpp

@@ -0,0 +1,112 @@
+/**
+ *
+ *  @file inflight_timeout.cpp
+ *  @author Gaspard Kirira
+ *
+ *  Vix.cpp
+ *
+ */
+#include <cassert>
+#include <chrono>
+#include <filesystem>
+#include <iostream>
+#include <memory>
+
+#include <vix/net/NetworkProbe.hpp>
+#include <vix/sync/engine/SyncEngine.hpp>
+#include <vix/sync/outbox/FileOutboxStore.hpp>
+#include <vix/sync/outbox/Outbox.hpp>
+
+#include "fake_http_transport.hpp"
+
+static std::int64_t now_ms()
+{
+  using namespace std::chrono;
+  return duration_cast<milliseconds>(steady_clock::now().time_since_epoch()).count();
+}
+
+static void reset_dir(const std::filesystem::path &dir)
+{
+  std::error_code ec;
+  std::filesystem::remove_all(dir, ec);
+  std::filesystem::create_directories(dir, ec);
+}
+
+static int run_inflight_timeout()
+{
+  using namespace vix::sync;
+  using namespace vix::sync::outbox;
+  using namespace vix::sync::engine;
+
+  const std::filesystem::path dir = "./.vix_example_sync_inflight";
+  reset_dir(dir);
+
+  auto store = std::make_shared<FileOutboxStore>(FileOutboxStore::Config{
+      .file_path = dir / "outbox.json",
+      .pretty_json = true,
+      .fsync_on_write = false});
+
+  auto outbox = std::make_shared<Outbox>(
+      Outbox::Config{.owner = "example-sync-inflight"},
+      store);
+
+  auto probe = std::make_shared<vix::net::NetworkProbe>(
+      vix::net::NetworkProbe::Config{},
+      []
+      { return true; });
+
+  auto transport = std::make_shared<FakeHttpTransport>();
+  transport->setDefault({.ok = true});
+
+  SyncEngine::Config ecfg;
+  ecfg.worker_count = 1;
+  ecfg.batch_limit = 10;
+  ecfg.idle_sleep_ms = 0;
+  ecfg.offline_sleep_ms = 0;
+  ecfg.inflight_timeout_ms = 50;
+
+  SyncEngine engine(ecfg, outbox, probe, transport);
+
+  Operation op;
+  op.kind = "http.post";
+  op.target = "/api/messages";
+  op.payload = R"({"text":"hello offline"})";
+
+  const auto t0 = now_ms();
+  const auto id = outbox->enqueue(op, t0);
+
+  const bool claimed = outbox->claim(id, t0);
+  assert(claimed);
+
+  {
+    const auto saved = store->get(id);
+    assert(saved.has_value());
+    assert(saved->status == OperationStatus::InFlight);
+  }
+
+  const auto t1 = t0 + 60;
+  engine.tick(t1);
+
+  {
+    const auto saved = store->get(id);
+    assert(saved.has_value());
+    assert(saved->status != OperationStatus::InFlight);
+    assert(saved->status == OperationStatus::Failed || saved->status == OperationStatus::Done);
+  }
+
+  engine.tick(t1 + 1);
+
+  const auto final = store->get(id);
+  assert(final.has_value());
+  assert(final->status == OperationStatus::Done);
+
+  assert(transport->callCount() >= 1);
+
+  std::cout << "[sync] OK: inflight timeout requeues stuck ops and they complete\n";
+  return 0;
+}
+
+int main()
+{
+  return run_inflight_timeout();
+}