# leopard

**Repository Path**: mirrors_wallyqs/leopard

## Basic Information

- **Project Name**: leopard
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-19
- **Last Updated**: 2026-03-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

= Leopard NATS ServiceApi Server
bougyman <me@bougyman.com>
: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]

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