jstreams 0.1.0.alpha

data/README.md

@@ -0,0 +1,140 @@
+# jstreams
+
+[![CircleCI](https://circleci.com/gh/jstotz/jstreams.svg?style=svg)](https://circleci.com/gh/jstotz/jstreams)
+[![Maintainability](https://api.codeclimate.com/v1/badges/f37990e1cb4727d2ae71/maintainability)](https://codeclimate.com/github/jstotz/jstreams/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/f37990e1cb4727d2ae71/test_coverage)](https://codeclimate.com/github/jstotz/jstreams/test_coverage)
+
+A distributed streaming platform for Ruby built on top of Redis Streams.
+
+Provides a multi-threaded publisher/subscriber.
+
+## Project Status
+
+This is alpha software and not suitable for production use.
+
+## Roadmap
+
+- [X] Load balancing across named consumer groups
+- [X] Automatically reclaim messages when consumers die
+- [X] Multi-threaded subscribers
+- [X] Automatic checkpoint storage
+- [X] Configurable message serialization
+- [ ] Configurable retry logic
+- [ ] Replay streams from a given checkpoint
+- [ ] Wildcard subscriptions
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jstreams'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install jstreams
+
+## Usage
+
+### Publisher
+
+```ruby
+jstreams = Jstreams::Context.new
+
+jstreams.publish(
+  :users,
+  event: 'user_created',
+  user_id: 1,
+  name: 'King Buzzo'
+)
+
+jstreams.publish(
+  :users,
+  event: 'user_logged_in'
+  user_id: 1
+)
+```
+
+### Subscriber
+
+```ruby
+jstreams = Jstreams::Context.new
+
+jstreams.subscribe(
+  :user_activity_logger,
+  :users
+) { |message, _stream, _subscriber| logger.info "User #{name}" }
+
+jstreams.subscribe(
+  :subscriber,
+  %w[foo:* bar:*]
+) { |message, _stream, _subscriber| logger.info "User #{name}" }
+
+# Spawns subscriber threads and blocks
+jstreams.run
+```
+
+### Replay
+
+Starts a temporary copy of the given subscriber until messages have been replayed up to the checkpoint stored at the time replay is called.
+
+```ruby
+jstreams.replay(:user_activity_logger, from: message_id)
+```
+
+### Retries
+
+By default subscribers will process messages indefinitely until successful.
+
+```ruby
+# TODO
+```
+
+### Serialization
+
+```ruby
+class Serializer
+  MESSAGE_TYPES = {
+    user_created: UserCreatedMessage, user_logged_in: UserLoggedInMessage
+  }
+
+  def serialize(type, message)
+    message_class(type).serialize(message)
+  end
+
+  def deserialize(type, message)
+    message_class(type).deserialize(message)
+  end
+
+  private
+
+  def message_class(type)
+    MESSAGE_TYPES.fetch(type) { raise "Unknown message type: #{type}" }
+  end
+end
+
+jstreams = Jstreams::Context.new(serializer: Serializer)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/jstreams. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the jstreams project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/jstreams/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "jstreams"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/basic/docker-compose.yml

@@ -0,0 +1,28 @@
+version: "3.7"
+
+x-example: &example
+  working_dir: /opt/jstreams/examples/basic
+  build:
+    context: ../..
+  environment:
+    REDIS_URL: redis://redis
+  volumes:
+    - ../..:/opt/jstreams
+  depends_on:
+    - redis
+
+services:
+  redis:
+    image: redis:5
+
+  publisher:
+    <<: *example
+    command: ["ruby", "example_publisher.rb"]
+
+  subscriber1:
+    <<: *example
+    command: ["ruby", "example_subscriber.rb", "subscriber1"]
+
+  subscriber2:
+    <<: *example
+    command: ["ruby", "example_subscriber.rb", "subscriber2"]

data/examples/basic/example_publisher.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'jstreams'
+
+STDOUT.sync = true
+logger = Logger.new(STDOUT)
+
+logger.info 'Starting publisher...'
+
+jstreams = Jstreams::Context.new logger: logger
+
+loop do
+  body = "hello #{Time.now}"
+  id = jstreams.publish('mystream', body)
+  logger.info "published: #{id} - #{body}"
+  sleep(1)
+end

data/examples/basic/example_subscriber.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'logger'
+require 'jstreams'
+
+STDOUT.sync = true
+
+USAGE = 'usage: ruby subscriber.rb [subscriber_key]'
+
+subscriber_key = ARGV[0] || abort(USAGE)
+
+puts "Starting subscriber #{subscriber_key}..."
+
+logger = Logger.new(STDOUT)
+jstreams = Jstreams::Context.new(logger: logger)
+
+jstreams.subscribe(
+  'mysubscriber',
+  'mystream',
+  key: subscriber_key
+) { |message| logger.info "Subscriber got a message: #{message.inspect}" }
+
+jstreams.run

data/jstreams.gemspec

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+if ENV['DOCKER_BUILD']
+  version = '0.0.0'
+else
+  lib = File.expand_path('lib', __dir__)
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+  require 'jstreams/version'
+  version = Jstreams::VERSION
+end
+
+Gem::Specification.new do |spec|
+  spec.name = 'jstreams'
+  spec.version = version
+  spec.authors = ['Jay Stotz']
+  spec.email = %w[jason.stotz@gmail.com]
+
+  spec.summary =
+    'A distributed pub/sub messaging system for Ruby based on Redis Streams'
+  spec.homepage = 'https://github.com/jstotz/jstreams'
+  spec.license = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+    spec.metadata['homepage_uri'] = spec.homepage
+    spec.metadata['source_code_uri'] = 'https://github.com/jstotz/jstreams'
+    spec.metadata['changelog_uri'] =
+      'https://github.com/jstotz/jstreams/blob/master/CHANGELOG.md'
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+            'public gem pushes.'
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files =
+    Dir.chdir(File.expand_path(__dir__)) do
+      unless ENV['DOCKER_BUILD']
+        `git ls-files -z`.split("\x0").reject do |f|
+          f.match(%r{^(test|spec|features)/})
+        end
+      end
+    end
+
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = %w[lib]
+
+  spec.add_dependency 'concurrent-ruby'
+  spec.add_dependency 'connection_pool'
+  spec.add_dependency 'redis', '>= 4.1.0'
+
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 10.0'
+end

data/lib/jstreams.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'redis'
+require 'jstreams/version'
+require 'jstreams/context'
+
+module Jstreams
+  class Error < StandardError; end
+end

data/lib/jstreams/consumer_group.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'redis'
+
+# :nodoc:
+module Jstreams
+  ##
+  # A Redis streams Consumer Group
+  class ConsumerGroup
+    ##
+    # @param [String] name Consumer group name
+    # @param [String] stream Stream name
+    # @param [Redis] redis Redis connection
+    def initialize(name:, stream:, redis:)
+      @name = name
+      @stream = stream
+      @redis = redis
+    end
+
+    ##
+    # Returns true if the group was created and false if it already existed
+    def create_if_not_exists(start_id: 0)
+      @redis.xgroup(:create, @stream, @name, start_id, mkstream: true)
+      true
+    rescue ::Redis::CommandError => e
+      raise e unless /BUSYGROUP/ =~ e.message
+      false
+    end
+  end
+
+  private_constant :ConsumerGroup
+end

data/lib/jstreams/context.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'connection_pool'
+
+require_relative 'serializers/json'
+require_relative 'publisher'
+require_relative 'subscriber'
+require_relative 'tagged_logging'
+
+module Jstreams
+  ##
+  # A collection of jstreams subscribers, their associated threads, and an interface for
+  # publishing messages.
+  class Context
+    attr_reader :redis_pool, :serializer, :logger
+
+    ##
+    # Initializes a jstreams context
+    #
+    # @param [String] redis_url Redis URL
+    # @param [Serializer] serializer Message serializer
+    # @param [Logger] logger Logger
+    def initialize(
+      redis_url: nil,
+      serializer: Serializers::JSON.new,
+      logger: Logger.new(ENV['JSTREAMS_VERBOSE'] ? STDOUT : File::NULL)
+    )
+      # TODO: configurable/smart default pool size
+      @redis_pool =
+        ::ConnectionPool.new(size: 10, timeout: 5) { Redis.new(url: redis_url) }
+      @serializer = serializer
+      @logger = TaggedLogging.new(logger)
+      @publisher =
+        Publisher.new(
+          redis_pool: @redis_pool, serializer: serializer, logger: @logger
+        )
+      @subscribers = []
+    end
+
+    ##
+    # Publishes a message to the given stream
+    #
+    # @param [String] stream Stream name
+    # @param [Hash] message Message to publish
+    def publish(stream, message)
+      @publisher.publish(stream, message)
+    end
+
+    ##
+    # Publishes a message to the given stream
+    #
+    # @param [String] name Subscriber name
+    # @param [String] streams Stream name or array of stream names to follow
+    # @param [String] key Unique consumer name
+    #
+    # @return [Subscriber] Handle to the registered subscriber. Can be used to #unsubscribe
+    def subscribe(name, streams, key: name, **kwargs, &block)
+      subscriber =
+        Subscriber.new(
+          redis_pool: @redis_pool,
+          logger: @logger,
+          serializer: @serializer,
+          name: name,
+          key: key,
+          streams: Array(streams),
+          handler: block,
+          **kwargs
+        )
+      @subscribers << subscriber
+      subscriber
+    end
+
+    ##
+    # Unsubscribes the given subscriber
+    #
+    # @param [Subscriber] subscriber Subscriber to unsubscribe
+    def unsubscribe(subscriber)
+      @subscribers.delete(subscriber)
+    end
+
+    ##
+    # Starts each registered subscriber
+    #
+    # @param [Boolean] wait Whether or not to block until subscribers shut down
+    def run(wait: true)
+      trap('INT') { shutdown }
+      Thread.abort_on_exception = true
+      @subscriber_threads =
+        @subscribers.map { |subscriber| Thread.new { subscriber.run } }
+      wait_for_shutdown if wait
+    end
+
+    ##
+    # Blocks until all subscribers are shut down
+    def wait_for_shutdown
+      @subscriber_threads.each(&:join)
+    end
+
+    ##
+    # Shuts down each registered subscriber
+    def shutdown
+      @subscribers.each(&:stop)
+    end
+  end
+end