simple_a2a 0.1.0 → 0.3.0

data/examples/11_sqlite_storage/Brewfile

@@ -0,0 +1 @@
+brew "sqlite3"

data/examples/11_sqlite_storage/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Pull in the gem's own runtime + development dependencies.
+gemspec path: "../../"
+
+gem "irb"
+gem "sqlite3"

data/examples/11_sqlite_storage/client.rb

@@ -0,0 +1,114 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage:
+#   bundle exec ruby examples/11_sqlite_storage/client.rb populate [ids_file]
+#   bundle exec ruby examples/11_sqlite_storage/client.rb verify   [ids_file]
+#
+# populate — sends three tasks and writes their IDs to ids_file (default:
+#            /tmp/a2a_sqlite_demo_ids.json) so the verify phase can find them.
+#
+# verify   — reads ids_file, retrieves each task from the (restarted) server,
+#            and confirms all tasks are still present with state "completed".
+#
+# The run script in this directory manages both phases automatically.
+
+require_relative "../common_config"
+require "json"
+
+URL      = "http://localhost:9292"
+IDS_FILE = ARGV[1] || "/tmp/a2a_sqlite_demo_ids.json"
+PHASE    = ARGV[0]
+
+unless %w[populate verify].include?(PHASE)
+  abort "Usage: client.rb <populate|verify> [ids_file]"
+end
+
+def divider = puts("─" * 60)
+
+client = A2A.client(url: URL)
+
+# ---------------------------------------------------------------------------
+# Phase: populate
+# ---------------------------------------------------------------------------
+if PHASE == "populate"
+  puts
+  puts "=== Phase 1: Populate — sending tasks to SQLite-backed server ==="
+  puts
+
+  card = client.agent_card
+  puts "  Agent : #{card.name}"
+  puts "  DB    : shown in server output"
+  puts
+
+  messages = [
+    "alpha — first message",
+    "beta  — second message",
+    "gamma — third message"
+  ]
+
+  ids = []
+  messages.each do |text|
+    task = client.send_task(message: A2A::Models::Message.user(text))
+    ids << task.id
+    puts "  sent  : #{text.strip}"
+    puts "  id    : #{task.id}"
+    puts "  state : #{task.status.state}"
+    puts "  reply : #{task.artifacts.first&.parts&.first&.text}"
+    puts
+  end
+
+  File.write(IDS_FILE, JSON.generate(ids))
+  puts "  IDs written to #{IDS_FILE}"
+  divider
+  puts
+  puts "Populate complete. The server will now be stopped and restarted."
+  puts "The same database file will be passed to the new server instance."
+  puts
+
+# ---------------------------------------------------------------------------
+# Phase: verify
+# ---------------------------------------------------------------------------
+else
+  puts
+  puts "=== Phase 2: Verify — confirming persistence after server restart ==="
+  puts
+
+  unless File.exist?(IDS_FILE)
+    abort "IDs file not found: #{IDS_FILE} — run the populate phase first."
+  end
+
+  ids = JSON.parse(File.read(IDS_FILE))
+  puts "  Reading #{ids.length} task IDs from #{IDS_FILE}"
+  puts
+
+  results = ids.map do |id|
+    task = client.get_task(id)
+    puts "  id    : #{id}"
+    puts "  state : #{task.status.state}"
+    puts "  reply : #{task.artifacts.first&.parts&.first&.text}"
+    puts
+    task
+  rescue A2A::Error => e
+    puts "  id    : #{id}  MISSING — #{e.message}"
+    puts
+    nil
+  end
+
+  divider
+
+  all_present   = results.none?(&:nil?)
+  all_completed = results.compact.all? { |t| t.status.state == "completed" }
+  count_ok      = results.length == ids.length
+
+  puts
+  puts "=== Verification ==="
+  puts "  All tasks present after restart : #{all_present   ? 'PASS' : 'FAIL'}"
+  puts "  All tasks in completed state    : #{all_completed ? 'PASS' : 'FAIL'}"
+  puts "  Task count matches (#{ids.length})         : #{count_ok     ? 'PASS' : 'FAIL'}"
+  puts
+
+  all_ok = all_present && all_completed && count_ok
+  puts(all_ok ? "All assertions passed." : "One or more assertions failed.")
+  exit(all_ok ? 0 : 1)
+end

data/examples/11_sqlite_storage/run

@@ -0,0 +1,154 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Custom run script for demo 11 — SQLite3 persistent storage.
+#
+# This demo proves *persistence across server restarts*, so it needs a
+# two-phase lifecycle:
+#
+#   Phase 1 — start server, populate tasks via client, stop server
+#   Phase 2 — restart server with the same DB file, verify tasks, stop server
+#
+# Dependencies are declared in the Gemfile and Brewfile alongside this script
+# rather than in-lined into the application code:
+#
+#   Brewfile — sqlite3 binary (macOS only; other platforms must provide it)
+#   Gemfile  — sqlite3 gem + simple_a2a gem (via gemspec path)
+#
+# The top-level `examples/run` launcher detects this file and delegates here.
+
+require "socket"
+
+DEMO_DIR        = File.expand_path(__dir__)
+RUBY            = RbConfig.ruby
+SERVER_PORT     = 9292
+STARTUP_TIMEOUT = 20
+DB_FILE         = "/tmp/a2a_sqlite_demo_tasks.db"
+IDS_FILE        = "/tmp/a2a_sqlite_demo_ids.json"
+
+BREWFILE  = File.join(DEMO_DIR, "Brewfile")
+GEMFILE   = File.join(DEMO_DIR, "Gemfile")
+SERVER_RB = File.join(DEMO_DIR, "server.rb")
+CLIENT_RB = File.join(DEMO_DIR, "client.rb")
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def banner(text)
+  bar = "─" * (text.length + 4)
+  puts "┌#{bar}┐"
+  puts "│  #{text}  │"
+  puts "└#{bar}┘"
+end
+
+def server_ready?(port)
+  TCPSocket.new("localhost", port).close
+  true
+rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, Errno::ETIMEDOUT
+  false
+end
+
+def wait_for_server(port, timeout)
+  deadline = Time.now + timeout
+  sleep 0.1 until server_ready?(port) || Time.now > deadline
+  server_ready?(port)
+end
+
+def bundle_env(gemfile)
+  { "BUNDLE_GEMFILE" => gemfile }
+end
+
+def start_server(gemfile, db_path)
+  pid = spawn(bundle_env(gemfile), RUBY, SERVER_RB, db_path, out: $stdout, err: $stderr)
+  unless wait_for_server(SERVER_PORT, STARTUP_TIMEOUT)
+    Process.kill("TERM", pid) rescue nil
+    abort "\nServer did not become ready within #{STARTUP_TIMEOUT}s — aborting."
+  end
+  puts "\n(server ready on port #{SERVER_PORT})\n\n"
+  pid
+end
+
+def stop_server(pid)
+  puts "\n(stopping server…)"
+  Process.kill("TERM", pid)
+  Process.wait(pid)
+rescue Errno::ESRCH, Errno::ECHILD
+  # already gone
+end
+
+# ---------------------------------------------------------------------------
+# Step 1 — ensure sqlite3 binary is available
+# ---------------------------------------------------------------------------
+banner "11_sqlite_storage — checking dependencies"
+
+unless system("which sqlite3 > /dev/null 2>&1")
+  if RUBY_PLATFORM =~ /darwin/
+    puts "sqlite3 binary not found — installing via Homebrew (Brewfile)..."
+    if system("brew bundle check --file=#{BREWFILE} > /dev/null 2>&1")
+      puts "(already satisfied)"
+    else
+      system("brew bundle install --file=#{BREWFILE}") or
+        abort "brew bundle install failed. Check #{BREWFILE} and try again."
+    end
+  else
+    abort <<~MSG
+
+      sqlite3 binary not found.
+      Install sqlite3 for your platform (e.g. apt install sqlite3) and retry.
+    MSG
+  end
+else
+  puts "(sqlite3 binary found)"
+end
+
+# ---------------------------------------------------------------------------
+# Step 2 — bundle install using the local Gemfile (adds sqlite3 to the bundle)
+# ---------------------------------------------------------------------------
+puts "(running bundle install for demo 11 Gemfile...)"
+system(bundle_env(GEMFILE), "bundle", "install", "--quiet") or
+  abort "bundle install failed. Check #{GEMFILE} and try again."
+puts "(bundle ready)"
+puts
+
+# ---------------------------------------------------------------------------
+# Clean up any leftover files from a previous run
+# ---------------------------------------------------------------------------
+File.delete(DB_FILE)  if File.exist?(DB_FILE)
+File.delete(IDS_FILE) if File.exist?(IDS_FILE)
+
+# ---------------------------------------------------------------------------
+# Phase 1 — populate
+# ---------------------------------------------------------------------------
+banner "11_sqlite_storage — Phase 1: populate"
+server_pid = start_server(GEMFILE, DB_FILE)
+
+banner "11_sqlite_storage — client (populate)"
+populate_ok = system(bundle_env(GEMFILE), RUBY, CLIENT_RB, "populate", IDS_FILE)
+
+stop_server(server_pid)
+
+abort "\nPopulate phase failed — aborting." unless populate_ok
+
+puts
+puts "(database preserved at #{DB_FILE})"
+puts "(sleeping 1s before restart...)"
+sleep 1
+
+# ---------------------------------------------------------------------------
+# Phase 2 — verify (same DB file, brand-new server process)
+# ---------------------------------------------------------------------------
+banner "11_sqlite_storage — Phase 2: verify (server restarted)"
+server_pid = start_server(GEMFILE, DB_FILE)
+
+banner "11_sqlite_storage — client (verify)"
+verify_ok = system(bundle_env(GEMFILE), RUBY, CLIENT_RB, "verify", IDS_FILE)
+
+stop_server(server_pid)
+
+# ---------------------------------------------------------------------------
+# Clean up temp files
+# ---------------------------------------------------------------------------
+File.delete(DB_FILE)  if File.exist?(DB_FILE)
+File.delete(IDS_FILE) if File.exist?(IDS_FILE)
+
+exit(verify_ok ? 0 : 1)

data/examples/11_sqlite_storage/server.rb

@@ -0,0 +1,131 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: BUNDLE_GEMFILE=examples/11_sqlite_storage/Gemfile \
+#          bundle exec ruby examples/11_sqlite_storage/server.rb [db_path]
+#
+# The run script in this directory manages the full lifecycle automatically.
+#
+# Demonstrates injecting a custom Storage::Base implementation (SQLite3) into
+# the simple_a2a server. The db_path argument lets two consecutive server
+# instances share the same database file, proving that tasks created in the
+# first run survive a full process restart.
+
+require "sqlite3"
+require_relative "../common_config"
+require "json"
+require "time"
+
+# ---------------------------------------------------------------------------
+# SqliteStorage — A2A::Storage::Base backed by SQLite3
+# ---------------------------------------------------------------------------
+class SqliteStorage < A2A::Storage::Base
+  def initialize(path)
+    @db    = SQLite3::Database.new(path)
+    @mutex = Mutex.new
+    @db.execute("PRAGMA journal_mode=WAL")
+    @db.execute("PRAGMA busy_timeout=5000")
+    setup_schema
+  end
+
+  def save(task)
+    @mutex.synchronize do
+      now = Time.now.iso8601
+      @db.execute(
+        "INSERT INTO tasks (id, data, created_at, updated_at) VALUES (?, ?, ?, ?) " \
+        "ON CONFLICT(id) DO UPDATE SET data=excluded.data, updated_at=excluded.updated_at",
+        [task.id, task.to_h.to_json, now, now]
+      )
+    end
+    task
+  end
+
+  def find(id)
+    row = @mutex.synchronize { @db.get_first_row("SELECT data FROM tasks WHERE id=?", [id]) }
+    return nil unless row
+    A2A::Models::Task.from_hash(JSON.parse(row[0]))
+  end
+
+  def find!(id)
+    find(id) or raise A2A::TaskNotFoundError, "Task #{id} not found"
+  end
+
+  def delete(id)
+    @mutex.synchronize { @db.execute("DELETE FROM tasks WHERE id=?", [id]) }
+  end
+
+  def list
+    rows = @mutex.synchronize { @db.execute("SELECT data FROM tasks ORDER BY rowid") }
+    rows.map { |row| A2A::Models::Task.from_hash(JSON.parse(row[0])) }
+  end
+
+  def size
+    @mutex.synchronize { @db.get_first_value("SELECT COUNT(*) FROM tasks") }
+  end
+
+  def clear
+    @mutex.synchronize { @db.execute("DELETE FROM tasks") }
+  end
+
+  private
+
+  def setup_schema
+    @db.execute(<<~SQL)
+      CREATE TABLE IF NOT EXISTS tasks (
+        id         TEXT PRIMARY KEY,
+        data       TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    SQL
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Executor — simple echo with a completion timestamp
+# ---------------------------------------------------------------------------
+class EchoExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    input = ctx.message.text_content.strip
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        name:  "reply",
+        parts: [A2A::Models::Part.text("echo: #{input} (completed at #{Time.now.utc.iso8601})")]
+      )
+    ])
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Startup
+# ---------------------------------------------------------------------------
+db_path = ARGV.first || File.join(__dir__, "tasks.db")
+storage  = SqliteStorage.new(db_path)
+
+card = A2A::Models::AgentCard.new(
+  name:         "PersistentEchoAgent",
+  version:      "1.0",
+  description:  "Stores tasks in SQLite3; survives server restarts",
+  capabilities: A2A::Models::AgentCapabilities.new,
+  skills: [
+    A2A::Models::AgentSkill.new(
+      name:        "echo",
+      description: "Echoes any text back with a completion timestamp"
+    )
+  ],
+  interfaces: [
+    A2A::Models::AgentInterface.new(
+      type:    "json-rpc",
+      url:     "http://localhost:9292",
+      version: "1.0"
+    )
+  ]
+)
+
+puts "Starting PersistentEchoAgent on http://localhost:9292"
+puts "  database: #{db_path}"
+puts "  existing tasks in DB: #{storage.size}"
+puts "Press Ctrl-C to stop."
+puts
+
+A2A.server(agent_card: card, executor: EchoExecutor.new, storage: storage).run