leopard 0.1.0 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 925e3c42a3a80193197765a65c4fa5301961310167cfc053e20c936c8a4e7054
-  data.tar.gz: f3e36504a2f3586f56f50b2f6bc4a25e6657b696b9f254e61b5baf33d20695cf
+  metadata.gz: a1e36e2390cc27892053da1e1e37648f5b9d525ea45490dbce1388073c0dd909
+  data.tar.gz: 4696ea5b7be68a9f9b7700f457240e398cfb20cd26f62ab6f2a196ab37a92215
 SHA512:
-  metadata.gz: 4987b6747903a013100ac5e8535688d4c7298d0f520cfcc81e207351c116c4cf9b77d89b07d09bc67714a2d2ed275aa5f898d519c0413fe66fac6974d878b016
-  data.tar.gz: ac0484d1a9267faae2daf88cdb4f8e693c0e6399abaf979e8e32e0e77b15e7d7bb32d4b39af4f72c685a9bce3cee5986a851836e309cb37b262b4d44b5a54c84
+  metadata.gz: 6dc17020cfdae2aadac7620feef13b52f9c362d6fdf2dfdc2ea16f52a9bfbca6538317c647f6ad000a21c6f9ca8279e2c7116143db4907d055239f19a3da369e
+  data.tar.gz: fd5ff2f5041715540adc05b8939e64fb5f5a7efca1d207a0c6144a0f608f2869c58034de4551fe3c55f2db756b17c607dde9afd20155145933662806952489c4

data/.release-please-config.json

@@ -0,0 +1,32 @@
+{
+  "packages": {
+    ".": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true,
+      "draft": false,
+      "prerelease": false,
+      "version-file": ".version.txt",
+      "extra-files": [
+        {
+          "type": "generic",
+          "path": "lib/leopard/version.rb"
+        },
+        {
+          "type": "generic",
+          "path": "oci/Gemfile"
+        }
+      ],
+      "exclude-paths": [
+        ".release-please-manifest.json",
+        ".version.txt",
+        "lib/leopard/version.rb",
+        ".rubocop.yml",
+        ".overcommit.yml",
+        "coverage/coverage.json"
+      ]
+    }
+  },
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
+}

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.3"
+}

data/.rubocop.yml

@@ -0,0 +1,46 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-minitest
+
+AllCops:
+  NewCops: enable
+
+Layout/LineLength:
+  Max: 140
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Bundler/OrderedGems:
+  TreatCommentsAsGroupSeparators: true
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Layout/ArrayAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  SafeAutoCorrect: true
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/HashSyntax:
+  Enabled: true
+  EnforcedShorthandSyntax: always

data/.version.txt

@@ -0,0 +1 @@
+0.1.3

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## [0.1.3](https://github.com/rubyists/leopard/compare/v0.1.2...v0.1.3) (2025-07-31)
+
+
+### Bug Fixes
+
+* Fixes the gem publisher, and adds missing .version.txt ([#11](https://github.com/rubyists/leopard/issues/11)) ([3dcbd3c](https://github.com/rubyists/leopard/commit/3dcbd3c1d687e04ce5fde85fef5c2d1c10a8a4cc))
+
+## [0.1.2](https://github.com/rubyists/leopard/compare/v0.1.1...v0.1.2) (2025-07-31)
+
+
+### Bug Fixes
+
+* Remove sequel cruft in ci config ([#9](https://github.com/rubyists/leopard/issues/9)) ([09a43e2](https://github.com/rubyists/leopard/commit/09a43e23c309167c56095dd608af9d79ff4f9b19))
+
+## [0.1.1](https://github.com/rubyists/leopard/compare/v0.1.0...v0.1.1) (2025-07-31)
+
+
+### Features
+
+* Adds gemspec and gemfile ([#1](https://github.com/rubyists/leopard/issues/1)) ([972dc72](https://github.com/rubyists/leopard/commit/972dc72de804ca10db5cf869d0ea996a94ac9722))
+* Adds rakefile back ([#3](https://github.com/rubyists/leopard/issues/3)) ([271592c](https://github.com/rubyists/leopard/commit/271592c357e07d58de085297850533eaae60a285))
+* Adds settings to module ([9ff0942](https://github.com/rubyists/leopard/commit/9ff0942dddd86bf4f97bc82626cc7bb35e4115ac))
+* Basic functionality for serving apis ([#4](https://github.com/rubyists/leopard/issues/4)) ([9ff0942](https://github.com/rubyists/leopard/commit/9ff0942dddd86bf4f97bc82626cc7bb35e4115ac))
+* Initial readme ([4ea9f34](https://github.com/rubyists/leopard/commit/4ea9f341c9df6096b8df3595ff6a075eb9b5c4f6))
+
+
+### Bug Fixes
+
+* Corrects gemname in publish-gem.sh ([9ff0942](https://github.com/rubyists/leopard/commit/9ff0942dddd86bf4f97bc82626cc7bb35e4115ac))
+* Corrects the version ([#7](https://github.com/rubyists/leopard/issues/7)) ([a3de532](https://github.com/rubyists/leopard/commit/a3de5320a8c54e9ca6724b6e90812bb5b1b7d150))

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'minitest/test_task'
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+Minitest::TestTask.create(:test) do |task|
+  task.libs << 'lib'
+  task.libs << 'test'
+  task.test_globs = ['test/*/**/*.rb']
+  task.warning = true
+end
+
+task default: %i[rubocop test]

data/Readme.adoc

@@ -1,9 +1,111 @@
-# Leopard Nats ServiceApi Server
+= Leopard NATS ServiceApi Server
 bougyman <me@bougyman.com>
-: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`.
+* Grouping of endpoints with `#group`
+* Simple concurrency via `#run` with a configurable number of instances.
+* JSON aware message wrapper that gracefully handles parse errors.
+* Middleware support using `#use`.
+* Railway Oriented Design, using {dry-monads} for success and failure handling.
+* {dry-configurable} settings container.
+* `#logger` defaults to SemanticLogger (adjustable as the `#logger=` setting)
+
+== Requirements
+
+* Ruby >= 3.4.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

data/ci/build_image.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+
+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")
+
+repo_top=$(git rev-parse --show-toplevel)
+cd "$repo_top" || {
+    printf "Could not cd to %s\n" "$repo_top" >&2
+    exit 1
+}
+
+base_dir=$(basename "$(pwd)")
+: "${UBUNTU_VERSION:=bookworm}"
+: "${BUILD_CONTEXT:=$(pwd)}"
+: "${IMAGE_NAME:=$base_dir}"
+: "${LICENSE:=MIT}"
+: "${REGISTRY:=ghcr.io}"
+: "${RUBY_VERSION:=3.3.6}"
+: "${REGISTRY_TOKEN:=$GITHUB_TOKEN}"
+
+base_image_tag="$RUBY_VERSION-$UBUNTU_VERSION"
+base_exists=$(skopeo list-tags docker://docker.io/ruby |jq -r "any(.Tags[] == \"$base_image_tag\"; .)")
+if [ "$base_exists" = "false" ]
+then
+    printf "Base image %s does not exist at docker.io/ruby, cannot build.\n" "$base_image_tag" >&2
+    exit 99
+fi
+
+usage() { # {{{
+    cat <<-EOT
+    Build an image, optionally pushing it to the registry
+
+    Usage: $0 <options> <image_tag>
+        Options:
+            -c CONTAINERFILE  Path to the containerfile (default: ./oci/Containerfile)
+            -C CONTEXT        Build context (default: $BUILD_CONTEXT)
+            -i NAME           Name of the image (default: $IMAGE_NAME)
+            -l LICENSE        License of the image (default: $LICENSE)
+            -r REGISTRY       Registry to push the image to when -p is given (default: $REGISTRY)
+            -p                Push the image to the registry
+            -h                Show help / usage
+EOT
+} # }}}
+
+die() { # {{{
+    local -i code
+    code=$1
+    shift
+    error "$*"
+    printf "\n" >&2
+    usage >&2
+    # shellcheck disable=SC2086
+    exit $code
+} # }}}
+
+## Logging functions # {{{
+log() { # {{{
+    printf "%s [%s] <%s> %s\n" "$(date '+%Y-%m-%d %H:%M:%S.%6N')" "$$" "${just_me:-$0}" "$*"
+} # }}}
+
+debug() { # {{{
+    [ $verbose -lt 2 ] && return 0
+    # shellcheck disable=SC2059
+    log_line=$(printf "$@")
+    log "[DEBUG] $log_line" >&2
+} # }}}
+
+warn() { # {{{
+    # shellcheck disable=SC2059
+    log_line=$(printf "$@")
+    log "[WARN] $log_line" >&2
+} # }}}
+
+error() { # {{{
+    # shellcheck disable=SC2059
+    log_line=$(printf "$@")
+    log "[ERROR] $log_line" >&2
+} # }}}
+
+info() { # {{{
+    [ $verbose -lt 1 ] && return 0
+    # shellcheck disable=SC2059
+    log_line=$(printf "$@")
+    log "[INFO] $log_line" >&2
+} # }}}
+# }}}
+
+push=0
+verbose=0
+while getopts :hpvc:C:i:l:r: opt # {{{
+do
+    case $opt in
+        c)
+            CONTAINERFILE=$OPTARG
+            ;;
+        C)
+            BUILD_CONTEXT=$OPTARG
+            ;;
+        i)
+            IMAGE_NAME=$OPTARG
+            ;;
+        l)
+            LICENSE=$OPTARG
+            ;;
+        r)
+            REGISTRY=$OPTARG
+            ;;
+        p)
+            push=1
+            ;;
+        v)
+            verbose=$((verbose + 1))
+            ;;
+        h)
+            usage
+            exit
+            ;;
+        :)
+            printf "Option %s requires an argument\n" "$OPTARG" >&2
+            usage >&2
+            exit 28
+            ;;
+        ?)
+            printf "Invalid option '%s'\n" "$OPTARG" >&2
+            usage >&2
+            exit 27
+            ;;
+    esac
+done # }}}
+shift $((OPTIND-1))
+
+tag=$1
+[ -z "$tag" ] && die 1 "Missing image tag"
+shift
+
+# Check for extra argument
+if [ $# -gt 0 ]; then
+    # If we have the special argument '--' we shift it away, otherwise we die
+    [ "$1" != '--' ] && die 2 "Too many arguments"
+    # Once this is shifted away, the rest of the arguments are passed to the build command, below
+    shift
+fi
+
+if [ -z "$CONTAINERFILE" ]; then
+    printf "No containerfile specified, looking for default locations\n"
+    for containerfile in Containerfile Dockerfile
+    do
+        if [ -f ./oci/"$containerfile" ]; then
+            debug "Found ./oci/%s\n" "$containerfile"
+            containerfile=./oci/"$containerfile"
+            break
+        fi
+        if [ -f "$containerfile" ]; then
+            debug "Found %s\n" "$containerfile"
+            break
+        fi
+    done
+else
+    [ -f "$CONTAINERFILE" ] || die 3 "Containerfile '$CONTAINERFILE' not found"
+    debug "Using containerfile %s\n" "$CONTAINERFILE"
+    containerfile=$CONTAINERFILE
+fi
+
+[ -f "$containerfile" ] || die 4 "No containerfile found"
+
+[ -d "$BUILD_CONTEXT" ] || die 5 "Build context '$BUILD_CONTEXT' not found"
+
+debug 'Building image from %s in in %s\n' "$containerfile" "$here"
+# Build the image
+if command -v podman 2>/dev/null
+then
+    runtime=podman
+elif command -v docker 2>/dev/null
+then
+    runtime=docker
+else
+    die 6 "No container runtime found"
+fi
+
+revision=$(git rev-parse HEAD)
+shortref=$(git rev-parse --short "$revision")
+repo_url=$(git remote get-url origin)
+if [ -z "$repo_url" ]
+then
+    die 7 "No remote found"
+fi
+if [[ $repo_url == *github.com/* ]]
+then
+    owner_and_repo=${repo_url#*github.com/}
+else
+    owner_and_repo=${repo_url##*:}
+fi
+# Get rid of the trailing .git
+service=$(basename "$owner_and_repo" .git)
+owner=$(dirname "$owner_and_repo")
+
+full_tag=$IMAGE_NAME:$tag
+# Pass any extra arguments to the build command ("$@" contains the rest of the arguments)
+$runtime build --tag "$full_tag" "$@" \
+               --label org.opencontainers.image.created="$(date --utc --iso-8601=seconds)" \
+               --label org.opencontainers.image.description="Image for $service" \
+               --label org.opencontainers.image.licenses="$LICENSE" \
+               --label org.opencontainers.image.revision="$revision" \
+               --label org.opencontainers.image.url="$repo_url" \
+               --label org.opencontainers.image.title="$IMAGE_NAME" \
+               --label org.opencontainers.image.source="Generated by ruby-automation's build_image.sh ($USER@$HOSTNAME)" \
+               --label org.opencontainers.image.version="$full_tag" \
+               --label shortref="$shortref" \
+               --build-arg UBUNTU_VERSION="$UBUNTU_VERSION" \
+               --build-arg RUBY_VERSION="$RUBY_VERSION" \
+               -f "$containerfile" "$BUILD_CONTEXT" || die 8 "Failed to build image"
+
+[ $push -eq 1 ] || exit 0
+if ! $runtime login --get-login "$REGISTRY" >/dev/null 2>/dev/null
+then
+    printf "Not logged in to '%s', trying to login\n" "$REGISTRY" >&2
+    [ -z "$REGISTRY_TOKEN" ] && die 9 "No REGISTRY_TOKEN (nor GITHUB_TOKEN) set, cannot login"
+    printf "%s" "$REGISTRY_TOKEN" | $runtime login -u "$REGISTRY_TOKEN" --password-stdin "$REGISTRY" || die 10 "Failed to login to $REGISTRY"
+fi
+
+# Split 1.2.3 into 1.2.3, 1.2, 1. We want to tag our image with all 3 of these
+mapfile -t tags < <(echo "$tag" | awk -F'.' 'NF==3{print; print $1"."$2; print $1; next} NF==2{print; print $1; next} {print}')
+for t in "${tags[@]}"
+do
+    new_tag=$IMAGE_NAME:$t
+    registry_image_name="$REGISTRY/$owner/$new_tag"
+    if [ "$runtime" = "podman" ]
+    then
+        if [ "$full_tag" != "$new_tag" ]
+        then
+            debug "Tagging %s as %s\n" "$full_tag" "$new_tag"
+            podman tag "$full_tag" "$new_tag" || die 11 "Failed to tag image $full_tag as $new_tag"
+        fi
+        podman push "$new_tag" "$registry_image_name" || die 12 "Failed to push image $new_tag to $registry_image_name"
+    else
+        debug "Tagging %s as %s\n" "$full_tag" "$registry_image_name"
+        docker tag "$full_tag" "$registry_image_name" || die 13 "Failed to tag image $full_tag as $registry_image_name"
+        docker push "$registry_image_name" || die 14 "Failed to push image $new_tag to $registry_image_name"
+    fi
+done
+
+# vim: set foldmethod=marker et ts=4 sts=4 sw=4 ft=bash :

data/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 = ">"
+	}
+}

data/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 "$@"

data/ci/publish-gem.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+
+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)
+root=$(cd "$here/.." && pwd)
+just_me=$(basename "$me")
+
+: "${GEM_NAME:=leopard}"
+: "${GIT_ORG:=rubyists}"
+
+GEM_HOST=$1
+: "${GEM_HOST:=rubygems}"
+
+case "$GEM_HOST" in
+    rubygems)
+        gem_key='rubygems'
+        gem_host='https://rubygems.org'
+        ;;
+    github)
+        gem_key='github'
+        gem_host="https://rubygems.pkg.github.com/$GIT_ORG"
+        # Replace the gem host in the gemspec, so it allows pushing to the GitHub package registry
+        sed --in-place=.bak -e "s|https://rubygems.org|https://rubygems.pkg.github.com/$GIT_ORG|" "$here/../$GEM_NAME".gemspec
+        # Restore the original gemspec after the script finishes
+        trap 'mv -v "$here/../$GEM_NAME".gemspec.bak "$here/../$GEM_NAME".gemspec' EXIT
+        ;;
+    *)
+        printf 'Unknown GEM_HOST: %s\n' "$GEM_HOST" >&2
+        exit 1
+        ;;
+esac
+
+# We only want this part running in CI, with no ~/.gem dir
+# For local testing, you should have a ~/.gem/credentials file with
+# the keys you need to push to rubygems or github
+if [ ! -d ~/.gem ]
+then
+    if [ -z "$GEM_TOKEN" ]
+    then
+        printf 'No GEM_TOKEN provided, cannot publish\n' >&2
+        exit 1
+    fi
+    mkdir -p ~/.gem
+    printf '%s\n:%s: %s\n' '---' "$gem_key" "$GEM_TOKEN" > ~/.gem/credentials
+    chmod 600 ~/.gem/credentials
+fi
+
+bundle exec gem build
+if [ -f "$here"/../.version.txt ]
+then
+    version=$(<"$here"/../.version.txt)
+else
+    version=$(git describe --tags --abbrev=0 | sed -e 's/^v//')
+fi
+
+if [ -z "$version" ]
+then
+    gem="$(ls "$here"/../"$GEM_NAME"-*.gem | tail -1)"
+else
+    gem="$(printf '%s/../%s-%s.gem' "$here" "$GEM_NAME" "$version")"
+fi
+
+if [ ! -f "$gem" ]
+then
+    printf 'No gem file found: %s\n' "$gem" >&2
+    exit 1
+fi
+
+if [[ "${TRACE:-false}" == true || "${ACTIONS_STEP_DEBUG:-false}" == true ]]
+then
+    printf "DEBUG: [%s] Building And Publishing %s to %s\n" "$just_me" "$gem" "$gem_host" >&2
+fi
+
+bundle exec gem push -k "$gem_key" --host "$gem_host" "$(basename "$gem")"
+
+# vim: set foldmethod=marker et ts=4 sts=4 sw=4 ft=bash :

data/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

data/lib/leopard/errors.rb

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

data/lib/leopard/message_wrapper.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Rubyists
+  module Leopard
+    class MessageWrapper
+      # @!attribute [r] raw
+      # @return [NATS::Message] The original NATS message.
+      #
+      # @!attribute [r] data
+      # @return [Object] The parsed data from the NATS message.
+      #
+      # @!attribute [r] headers
+      # @return [Hash] The headers from the NATS message.
+      attr_reader :raw, :data, :headers
+
+      # @param nats_msg [NATS::Message] The NATS message to wrap.
+      def initialize(nats_msg)
+        @raw     = nats_msg
+        @data    = parse_data(nats_msg.data)
+        @headers = nats_msg.header.to_h
+      end
+
+      # @param payload [Object] The payload to respond with.
+      #
+      # @return [void]
+      def respond(payload)
+        raw.respond(serialize(payload))
+      end
+
+      # @param err [String, Exception] The error message or exception to respond with.
+      # @param code [Integer] The HTTP status code to use for the error response.
+      #
+      # @return [void]
+      def respond_with_error(err, code: 500)
+        raw.respond_with_error(err.to_s, code:)
+      end
+
+      private
+
+      # Parses the raw data from the NATS message.
+      # Assumes the data is in JSON format.
+      # If parsing fails, it returns the raw string.
+      #
+      # @param raw [String] The raw data from the NATS message.
+      #
+      # @return [Object] The parsed data, or the raw string if parsing fails.
+      def parse_data(raw)
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        raw
+      end
+
+      # Serializes the object to a JSON string if it is not already a string.
+      # @param obj [Object] The object to serialize.
+      #
+      # @return [String] The serialized JSON string or the original string.
+      def serialize(obj)
+        obj.is_a?(String) ? obj : JSON.generate(obj)
+      end
+    end
+  end
+end

data/lib/leopard/nats_api_server.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require 'nats/client'
+require 'dry/monads'
+require 'concurrent'
+require_relative '../leopard'
+require_relative 'message_wrapper'
+
+module Rubyists
+  module Leopard
+    module NatsApiServer
+      include Dry::Monads[:result]
+      extend Dry::Monads[:result]
+
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.extend(Dry::Monads[:result])
+        base.include(SemanticLogger::Loggable)
+      end
+
+      module ClassMethods
+        def endpoints = @endpoints ||= []
+        def groups = @groups ||= {}
+        def middleware = @middleware ||= []
+
+        # Define an endpoint for the NATS API server.
+        #
+        # @param name [String] The name of the endpoint.
+        # @param subject [String, nil] The NATS subject to listen on. Defaults to the endpoint name.
+        # @param queue [String, nil] The NATS queue group to use. Defaults to nil.
+        # @param group [String, nil] The group this endpoint belongs to. Defaults to nil.
+        # @param handler [Proc] The block that will handle incoming messages.
+        #
+        # @return [void]
+        def endpoint(name, subject: nil, queue: nil, group: nil, &handler)
+          endpoints << {
+            name:,
+            subject: subject || name,
+            queue:,
+            group:,
+            handler:,
+          }
+        end
+
+        # Define a group for organizing endpoints.
+        #
+        # @param name [String] The name of the group.
+        # @param group [String, nil] The parent group this group belongs to. Defaults to nil.
+        # @param queue [String, nil] The NATS queue group to use for this group. Defaults to nil.
+        #
+        # @return [void]
+        def group(name, group: nil, queue: nil)
+          groups[name] = { name:, parent: group, queue: }
+        end
+
+        # Use a middleware class for processing messages.
+        #
+        # @param klass [Class] The middleware class to use.
+        # @param args [Array] Optional arguments to pass to the middleware class.
+        # @param block [Proc] Optional block to pass to the middleware class.
+        #
+        # @return [void]
+        def use(klass, *args, &block)
+          middleware << [klass, args, block]
+        end
+
+        # Start the NATS API server.
+        # This method connects to the NATS server and spawns multiple instances of the API server.
+        #
+        # @param nats_url [String] The URL of the NATS server to connect to.
+        # @param service_opts [Hash] Options for the NATS service.
+        # @param instances [Integer] The number of instances to spawn. Defaults to 1.
+        # @param blocking [Boolean] If false, does not block current thread after starting the server. Defaults to true.
+        #
+        # @return [void]
+        def run(nats_url:, service_opts:, instances: 1, blocking: true)
+          logger.info 'Booting NATS API server...'
+          # Return the thread pool if non-blocking
+          return spawn_instances(nats_url, service_opts, instances) unless blocking
+
+          # Otherwise, just sleep the main thread forever
+          sleep
+        end
+
+        private
+
+        # Spawns multiple instances of the NATS API server.
+        #
+        # @param url [String] The URL of the NATS server.
+        # @param opts [Hash] Options for the NATS service.
+        # @param count [Integer] The number of instances to spawn.
+        #
+        # @return [Concurrent::FixedThreadPool] The thread pool managing the worker threads.
+        def spawn_instances(url, opts, count)
+          pool = Concurrent::FixedThreadPool.new(count)
+          count.times do
+            eps = endpoints.dup
+            gps = groups.dup
+            pool.post { setup_worker(url, opts, eps, gps) }
+          end
+          pool
+        end
+
+        # Sets up a worker thread for the NATS API server.
+        # This method connects to the NATS server, adds the service, groups, and endpoints,
+        # and keeps the worker thread alive.
+        #
+        # @param url [String] The URL of the NATS server.
+        # @param opts [Hash] Options for the NATS service.
+        # @param eps [Array<Hash>] The list of endpoints to add.
+        # @param gps [Hash] The groups to add.
+        #
+        # @return [void]
+        def setup_worker(url, opts, eps, gps)
+          client  = NATS.connect url
+          service = client.services.add(**opts)
+          group_map = add_groups(service, gps)
+          add_endpoints service, eps, group_map
+          # Keep the worker thread alive
+          sleep
+        end
+
+        # Adds groups to the NATS service.
+        #
+        # @param service [NATS::Service] The NATS service to add groups to.
+        # @param gps [Hash] The groups to add, where keys are group names and values are group definitions.
+        #
+        # @return [Hash] A map of group names to their created group objects.
+        def add_groups(service, gps)
+          created = {}
+          gps.each_key { |name| build_group(service, gps, created, name) }
+          created
+        end
+
+        # Builds a group in the NATS service.
+        #
+        # @param service [NATS::Service] The NATS service to add the group to.
+        # @param defs [Hash] The group definitions, where keys are group names and values are group definitions.
+        # @param cache [Hash] A cache to store already created groups.
+        # @param name [String] The name of the group to build.
+        #
+        # @return [NATS::Group] The created group object.
+        def build_group(service, defs, cache, name)
+          return cache[name] if cache.key?(name)
+
+          gdef = defs[name]
+          raise ArgumentError, "Group #{name} not defined" unless gdef
+
+          parent = gdef[:parent] ? build_group(service, defs, cache, gdef[:parent]) : service
+          cache[name] = parent.groups.add(gdef[:name], queue: gdef[:queue])
+        end
+
+        # Adds endpoints to the NATS service.
+        #
+        # @param service [NATS::Service] The NATS service to add endpoints to.
+        # @param endpoints [Array<Hash>] The list of endpoints to add.
+        # @param group_map [Hash] A map of group names to their created group objects.
+        #
+        # @return [void]
+        def add_endpoints(service, endpoints, group_map)
+          endpoints.each do |ep|
+            parent = ep[:group] ? group_map[ep[:group]] : service
+            raise ArgumentError, "Group #{ep[:group]} not defined" if ep[:group] && parent.nil?
+
+            parent.endpoints.add(
+              ep[:name], subject: ep[:subject], queue: ep[:queue]
+            ) do |raw_msg|
+              wrapper = MessageWrapper.new(raw_msg)
+              dispatch_with_middleware(wrapper, ep[:handler])
+            end
+          end
+        end
+
+        # Dispatches a message through the middleware stack and handles it with the provided handler.
+        #
+        # @param wrapper [MessageWrapper] The message wrapper containing the raw message.
+        # @param handler [Proc] The handler to process the message.
+        #
+        # @return [void]
+        def dispatch_with_middleware(wrapper, handler)
+          app = ->(w) { handle_message(w.raw, handler) }
+          middleware.reverse_each do |(klass, args, blk)|
+            app = klass.new(app, *args, &blk)
+          end
+          app.call(wrapper)
+        end
+
+        # Handles a raw NATS message using the provided handler.
+        #
+        # @param raw_msg [NATS::Message] The raw NATS message to handle.
+        # @param handler [Proc] The handler to process the message.
+        #
+        # @return [void]
+        def handle_message(raw_msg, handler)
+          wrapper = MessageWrapper.new(raw_msg)
+          result  = instance_exec(wrapper, &handler)
+          process_result(wrapper, result)
+        rescue StandardError => e
+          logger.error 'Error processing message: ', e
+          wrapper.respond_with_error(e.message)
+        end
+
+        # Processes the result of the handler execution.
+        #
+        #
+        # @param wrapper [MessageWrapper] The message wrapper containing the raw message.
+        # @param result [Dry::Monads::Result] The result of the handler execution.
+        #
+        # @return [void]
+        # @raise [ResultError] If the result is not a Success or Failure monad.
+        def process_result(wrapper, result)
+          case result
+          in Dry::Monads::Success
+            wrapper.respond(result.value!)
+          in Dry::Monads::Failure
+            logger.error 'Error processing message: ', result.failure
+            wrapper.respond_with_error(result.failure)
+          else
+            logger.error('Unexpected result: ', result:)
+            raise ResultError, "Unexpected Response from Handler, must respond with a Success or Failure monad: #{result}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/settings.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'semantic_logger'
+
+module Rubyists
+  module Leopard
+    extend Dry::Configurable
+
+    setting :libroot, reader: true, default: Pathname(__FILE__).dirname.join('..').expand_path
+    setting :root, reader: true, default: libroot.join('..').expand_path
+    setting :logger, reader: true, default: SemanticLogger[:Leopard]
+  end
+end

data/lib/leopard/version.rb

@@ -3,7 +3,7 @@
 module Rubyists
   module Leopard
     # x-release-please-start-version
-    VERSION = '0.1.0'
+    VERSION = '0.1.3'
     # x-release-please-end
   end
 end

data/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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leopard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.3
 platform: ruby
 authors:
 - bougyman
@@ -9,6 +9,48 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: dry-monads
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
 - !ruby/object:Gem::Dependency
   name: nats-pure
   requirement: !ruby/object:Gem::Requirement
@@ -23,6 +65,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: semantic_logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
 description: Leopard is a puma-like server for managing concurrent NATS ServiceApi
   endpoint workers
 email:
@@ -31,7 +87,23 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".release-please-config.json"
+- ".release-please-manifest.json"
+- ".rubocop.yml"
+- ".version.txt"
+- CHANGELOG.md
+- Rakefile
 - Readme.adoc
+- ci/build_image.sh
+- ci/nats/accounts.txt
+- ci/nats/start.sh
+- ci/publish-gem.sh
+- examples/echo_endpoint.rb
+- lib/leopard.rb
+- lib/leopard/errors.rb
+- lib/leopard/message_wrapper.rb
+- lib/leopard/nats_api_server.rb
+- lib/leopard/settings.rb
 - lib/leopard/version.rb
 homepage: https://github.com/rubyists/leopard
 licenses: