feat: Basic functionality for serving apis

.gitignore

@@ -1,5 +1,6 @@
 *.gem
 *.rbc
+*.swp
 /.config
 /coverage/
 /InstalledFiles

Gemfile

@@ -5,13 +5,15 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in sequel-pgt_outbox.gemspec
 gemspec
 
-gem 'minitest'
-gem 'minitest-global_expectations'
-gem 'pry'
-gem 'rake'
-gem 'reline'
-gem 'rubocop'
-gem 'rubocop-minitest'
-gem 'rubocop-performance'
-gem 'rubocop-rake'
-gem 'simplecov'
+group :development, :test do
+  gem 'minitest'
+  gem 'minitest-global_expectations'
+  gem 'pry'
+  gem 'rake'
+  gem 'reline'
+  gem 'rubocop'
+  gem 'rubocop-minitest'
+  gem 'rubocop-performance'
+  gem 'rubocop-rake'
+  gem 'simplecov'
+end

Gemfile.lock

@@ -2,7 +2,11 @@ PATH
   remote: .
   specs:
     leopard (0.1.0)
+      concurrent-ruby (~> 1.1)
+      dry-configurable (~> 1.3)
+      dry-monads (~> 1.9)
       nats-pure (~> 2.5)
+      semantic_logger (~> 4)
 
 GEM
   remote: https://rubygems.org/
@@ -12,10 +16,22 @@ GEM
     coderay (1.1.3)
     concurrent-ruby (1.3.5)
     docile (1.4.1)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-core (1.1.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-monads (1.9.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
     io-console (0.8.1)
     json (2.13.1)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
+    logger (1.7.0)
     method_source (1.1.0)
     minitest (5.25.5)
     minitest-global_expectations (1.0.1)
@@ -68,6 +84,8 @@ GEM
       rubocop (>= 1.72.1)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
+    semantic_logger (4.17.0)
+      concurrent-ruby (~> 1.0)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
@@ -79,6 +97,7 @@ GEM
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
     uri (1.0.3)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   ruby

Readme.adoc

@@ -1,9 +1,109 @@
-# Leopard Nats ServiceApi Server
+= Leopard NATS ServiceApi Server
 bougyman <[email protected]>
-:service-api: https://github.com/rubyists/nats-pure.rb/blob/main/docs/service_api.md[Service API]
+:service-api: https://github.com/rubyists/nats-pure.rb/blob/main/docs/service_api.md[NATS Service API]
+:conventional-commits: https://www.conventionalcommits.org/en/v1.0.0/[Conventional Commits]
+:dry-configurable: https://github.com/dry-rb/dry-configurable[Dry::Configurable]
+:dry-monads: https://github.com/dry-rb/dry-monads[Dry::Monads]
 
-The leopard nats serviceapi server provides a simple concurrency
-model for NATS {service-api} workers. It is designed to be used
-similarly to a web server (inspired by puma), defining endpoints
-in your classes, and then serving them via the leopard (Ractor-based)
-service supervisor.
+Leopard is a small framework for building concurrent {service-api} workers.
+It uses `Concurrent::FixedThreadPool` to manage multiple workers in a single process and provides a
+minimal DSL for defining endpoints and middleware.
+
+== Features
+
+* Declarative endpoint definitions with `endpoint`.
+* Middleware support using `use`.
+* Simple concurrency via `run` with a configurable number of instances.
+* JSON aware message wrapper that gracefully handles parse errors.
+* Railway Oriented Design, using {dry-monads} for success and failure handling.
+* {dry-configurable} settings container.
+
+== Requirements
+
+* Ruby >= 3.3.0
+* A running NATS server with the Service API enabled.
+
+== Installation
+
+Add the gem to your project:
+
+[source,ruby]
+----
+# Gemfile
+gem 'leopard'
+----
+
+Then install it with Bundler.
+
+[source,bash]
+----
+$ bundle install
+----
+
+== Usage
+
+Create a service class and include `Rubyists::Leopard::NatsApiServer`.
+Define one or more endpoints. Each endpoint receives a
+`Rubyists::Leopard::MessageWrapper` object for each request to the {service-api} endpoint
+that service class is is subscribed to (subject:, or name:). The message handler/callback
+is expected to return a `Dry::Monads[:result]` object, typically a `Success` or `Failure`.
+
+[source,ruby]
+----
+class EchoService
+  include Rubyists::Leopard::NatsApiServer
+
+  endpoint :echo do |msg|
+    Success(msg.data)
+  end
+end
+----
+
+Run the service by providing the NATS connection details and service options:
+
+[source,ruby]
+----
+EchoService.run(
+  nats_url: 'nats://localhost:4222',
+  service_opts: { name: 'echo' },
+  instances: 4
+)
+----
+
+Middleware can be inserted around endpoint dispatch:
+
+[source,ruby]
+----
+class LoggerMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(wrapper)
+    puts "received: #{wrapper.data.inspect}"
+    @app.call(wrapper)
+  end
+end
+
+EchoService.use LoggerMiddleware
+----
+
+== Development
+
+The project uses Minitest and RuboCop. Run tests with Rake:
+
+[source,bash]
+----
+$ bundle exec rake
+----
+
+=== Conventional Commits (semantic commit messages)
+
+This project follows the {conventional-commits} specification.
+
+To contribute, please follow that commit message format,
+or your pull request may be rejected.
+
+== License
+
+MIT

ci/nats/accounts.txt

@@ -0,0 +1,27 @@
+# Client port of 4222 on all interfaces
+port: 4222
+
+# HTTP monitoring port
+monitor_port: 8222
+
+accounts: {
+        $SYS: {
+                users: [
+                        { user: sys, password: sys }
+                ]
+        }
+        ME: {
+          jetstream: enabled
+          users: [
+             { user: me, password: youandme }
+          ]
+        }
+}
+no_auth_user: me
+
+authorization {
+	default_permissions = {
+			publish = ">"
+			subscribe = ">"
+	}
+}

ci/nats/start.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+NATS_VERSION=2
+
+if readlink -f . >/dev/null 2>&1 # {{{ makes readlink work on mac
+then
+    readlink=readlink
+else
+    if greadlink -f . >/dev/null 2>&1
+    then
+        readlink=greadlink
+    else
+        printf "You must install greadlink to use this (brew install coreutils)\n" >&2
+    fi
+fi # }}}
+
+# Set here to the full path to this script
+me=${BASH_SOURCE[0]}
+[ -L "$me" ] && me=$($readlink -f "$me")
+here=$(cd "$(dirname "$me")" && pwd)
+just_me=$(basename "$me")
+export just_me
+
+cd "$here" || exit 1
+if command -v podman 2>/dev/null
+then
+    runtime=podman
+else
+    runtime=docker
+fi
+
+set -x
+exec "$runtime" run --rm -it -p 4222:4222 -p 6222:6222 -p 8222:8222 -v ./accounts.txt:/accounts.txt nats:"$NATS_VERSION" -js -c /accounts.txt "$@"

ci/publish-gem.sh

@@ -18,7 +18,7 @@ me=${BASH_SOURCE[0]}
 here=$(cd "$(dirname "$me")" && pwd)
 just_me=$(basename "$me")
 
-: "${GEM_NAME:=sequel-pgt_outbox}"
+: "${GEM_NAME:=leopard}"
 : "${GIT_ORG:=rubyists}"
 
 GEM_HOST=$1

examples/echo_endpoint.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/leopard/nats_api_server'
+
+# Example to echo the given message
+class EchoService
+  include Rubyists::Leopard::NatsApiServer
+
+  endpoint(:echo) { |msg| Success(msg.data) }
+end
+
+if __FILE__ == $PROGRAM_NAME
+  EchoService.run(
+    nats_url: 'nats://localhost:4222',
+    service_opts: { name: 'example.echo', version: '1.0.0' },
+    instances: 4,
+  )
+end

leopard.gemspec

@@ -2,7 +2,7 @@
 
 require_relative 'lib/leopard/version'
 
-Gem::Specification.new do |spec|
+Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.name = 'leopard'
   spec.version = Rubyists::Leopard::VERSION
   spec.authors = ['bougyman']
@@ -34,7 +34,11 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   # Uncomment to register a new dependency of your gem
+  spec.add_dependency 'concurrent-ruby', '~> 1.1'
+  spec.add_dependency 'dry-configurable', '~> 1.3'
+  spec.add_dependency 'dry-monads', '~> 1.9'
   spec.add_dependency 'nats-pure', '~> 2.5'
+  spec.add_dependency 'semantic_logger', '~> 4'
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

lib/leopard.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'dry/configurable'
+require 'pathname'
+require 'semantic_logger'
+SemanticLogger.add_appender(io: $stdout, formatter: :color)
+
+class Pathname
+  def /(other)
+    join other.to_s
+  end
+end
+
+module Rubyists
+  module Leopard
+  end
+end
+
+require_relative 'leopard/settings'
+require_relative 'leopard/version'
+require_relative 'leopard/errors'

lib/leopard/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Rubyists
+  module Leopard
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+  end
+end