redis-promise 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b87c0c0b6399954b74fb54514c2e7b97cb800a5cf6b18025d80cbdcf084d6402
+  data.tar.gz: de74a5dc0a7e53dfa122af59ec5410a0cb4addeacd848695b14d9da8eecbee70
+SHA512:
+  metadata.gz: bdd765fc640c834fb59eb97e1eda6bb59e8b5623f348ebbb677f5c1e067103824b64f192f89d5f302287e6e1a16b44503e251a2e751358be1d1dc83bf3a576d8
+  data.tar.gz: '080b8d58f3ad11e1305d9575d8393561584a7a452a04c1a7f2168216ba1371fb13346357d12586df60a8b2e0fb173a9cd221a24a292b1922b55700a441208d63'

data/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI Ruby
+
+on:
+  push:
+    branches: [ "main", "develop" ]
+  pull_request:
+    branches: [ "main", "develop" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    services:
+      # Label used to access the service container
+      redis:
+        # Docker Hub image
+        image: redis
+        # Set health checks to wait until redis has started
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          # Maps port 6379 on service container to the host
+          - 6379:6379
+    env:
+      CI: true
+      # The hostname used to communicate with the Redis service container
+      REDIS_HOST: localhost
+      # The default Redis port
+      REDIS_PORT: 6379
+    strategy:
+      matrix:
+        ruby-version: [ "3.3", "3.4", "4.0" ]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Install Ruby and gems
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - name: Run unit tests
+        run: bundle exec rake test
+
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      CI: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Install Ruby and gems
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+          bundler-cache: true
+      - name: Lint Ruby files
+        run: bundle exec rubocop --parallel
+
+  typecheck:
+    runs-on: ubuntu-latest
+    env:
+      CI: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Install Ruby and gems
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+          bundler-cache: true
+      - name: Typecheck Ruby files
+        run: bundle exec srb tc

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Add changes in new features here. Do not change the gem's version in pull/merge requests.
+
+### Changes
+-
+
+## [0.1.0] - 22.05.2026
+
+[Diff](https://github.com/Verseth/ruby-redis-promise/compare/v0.0.0...v0.1.0)
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateusz Drewniak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,151 @@
+# Redis::Promise
+
+This Ruby gem adds promises built on Redis.
+It enables you to resolve or reject a redis promise based on a key and
+await the result in another thread or on another machine/service.
+
+It can be used in tandem with job frameworks like `resque` or `sidekiq` in order
+to get back a result from an asynchronous task.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add redis-promise
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install redis-promise
+```
+
+## Usage
+
+This library adds two basic types `Redis::Promise` and `Redis::Promise::Resolver`.
+The Promise object can be used to await a resolved (success) value or a rejected (error) value.
+The Resolver object can be used to resolve or reject a promise. These two objects are tied together by a common redis key where the result gets stored.
+
+The basic idea is that you use a `Redis::Promise::Resolver` to resolve/reject the promise in one context eg. a thread or a different service. You then use `Redis::Promise` in another context to get (await) the value.
+
+### Threads
+
+Using the `Redis::Promise::create` helper to create a promise
+and its resolver at the same time.
+
+```rb
+require 'redis/promise'
+
+redis = Redis.new
+promise, resolver = Redis::Promise.create(redis)
+
+threads = []
+threads << Thread.new do
+  sleep(3)
+  resolver.resolve("OK!")
+end
+
+threads << Thread.new do
+  result = promise.await #=> "OK!"
+end
+
+threads.each(&:join)
+# should print "OK!" after 3 seconds
+```
+
+Creating a separate promise and resolver.
+Notice that the promise and resolver have to get their own
+Redis connection instances, that's because the `promise.await`
+blocks the entire redis connection making it impossible to resolve
+the promise using the same connection.
+
+```rb
+require 'redis/promise'
+
+redis = Redis.new
+threads = []
+
+promise = Redis::Promise.new(redis)
+threads << Thread.new do
+  puts promise.await #=> "OK!"
+end
+
+resolver = Redis::Promise::Resolver.new(redis, key: promise.key)
+threads << Thread.new do
+  sleep(3)
+  resolver.resolve("OK!")
+end
+
+threads.each(&:join)
+```
+
+### Resque
+
+You could use it in resque or any other job system to get the result from an asynchronous task.
+
+```rb
+# ========
+# job definition
+
+class SomeJob
+  @queue = :example
+
+  def self.perform(promise_key)
+    resolver = Redis::Promise::Resolver.new(
+      Resque.redis,
+      key: promise_key,
+    )
+    resolver.resolve(42)
+  end
+end
+
+# ========
+# some other place in the app
+
+promise = Redis::Promise.new(Resque.redis)
+Resque.enqueue(SomeJob, promise.key)
+
+promise.await #=> 42
+# you got a value back from a resque job!
+```
+
+#### Plugin
+
+There is an additional resque plugin you can load
+to make it more convenient.
+
+```rb
+require 'redis/promise/resque'
+
+class SomeJob
+  include Redis::Promise::Resque
+
+  @queue = :example
+
+  run do |n|
+    raise ArgumentError, "number must be positive: #{n}" if n < 0
+
+    n * 69
+  end
+end
+
+# enqueueing returns a promise
+promise = SomeJob.enqueue(42)
+promise.await #=> 2898
+
+# errors thrown in the job get caught and rethrown on await
+promise = SomeJob.enqueue(-2)
+promise.await
+#! Redis::Promise::RejectedError(value: "[ArgumentError]: number must be positive: -2")
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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 the created tag, 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/Verseth/ruby-redis-promise.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/redis/promise/resolver.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+class Redis
+  class Promise
+    # An object used to resolve or reject
+    # a redis promise.
+    class Resolver
+      #: Redis
+      attr_reader :redis
+
+      #: String
+      attr_reader :key
+
+      #: (Redis, ?id: String, ?namespace: String, ?key: String) -> void
+      def initialize(redis, id: SecureRandom.uuid_v4, namespace: 'global', key: "promise:#{namespace}:#{id}")
+        @redis = redis.dup #: Redis
+        @key = key
+      end
+
+      # Resolve the promise with the given value.
+      # The value gets serialized to JSON using `to_json`.
+      #
+      #: (top) -> void
+      def resolve(value)
+        serialized = { value: value }.to_json
+        push(serialized)
+      end
+
+      # Reject the promise with the given value.
+      # The value gets serialized to JSON using `to_json`.
+      #
+      #: (top) -> void
+      def reject(err)
+        serialized = { err: err }.to_json
+        push(serialized)
+      end
+
+      private
+
+      #: (String) -> void
+      def push(serialized)
+        @redis.rpush(@key, serialized)
+      end
+    end
+  end
+end

data/lib/redis/promise/resque.rb

@@ -0,0 +1,49 @@
+# typed: true
+# frozen_string_literal: true
+
+class Redis
+  class Promise
+    # An additional mixin for Resque jobs.
+    module Resque
+      extend T::Helpers
+
+      # Thrown when an invalid resque job class
+      # was used to enqueue a promise
+      class InvalidJobError < Error; end
+
+      # @requires_ancestor: Kernel
+      module ClassMethods
+        #: -> Redis
+        def promise_redis = ::Resque.redis
+
+        #: (*top) -> Promise
+        def enqueue(*args)
+          promise = Promise.new(promise_redis)
+          T.unsafe(::Resque).enqueue(self, promise.key, *args) # rubocop:disable Sorbet/ForbidTUnsafe
+
+          promise
+        end
+
+        #: (String, *untyped) -> void
+        def perform(promise_key, *args); end
+
+        #: { (untyped) -> void } -> void
+        def run(&block)
+          define_singleton_method :perform do |promise_key, *args|
+            promise = Promise::Resolver.new(promise_redis, key: promise_key)
+
+            begin
+              result = block.call(*args)
+              promise.resolve(result)
+            rescue StandardError => e
+              promise.reject("[#{e.class}]: #{e.message}")
+            end
+          end
+        end
+
+      end
+      mixes_in_class_methods(ClassMethods)
+
+    end
+  end
+end

data/lib/redis/promise/version.rb

@@ -0,0 +1,8 @@
+# typed: true
+# frozen_string_literal: true
+
+class Redis
+  class Promise # rubocop:disable Style/StaticClass
+    VERSION = '0.1.0'
+  end
+end

data/lib/redis/promise.rb

@@ -0,0 +1,83 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'redis'
+require 'json'
+require 'securerandom'
+require 'sorbet-runtime'
+require_relative 'promise/version'
+require_relative 'promise/resolver'
+
+class Redis
+  # An object used to wait for a value or an error
+  # from redis.
+  class Promise
+    # Base error for `Redis::Promise`
+    class Error < StandardError; end
+    # Thrown when the timeout has been exceeded while
+    # awaiting a `Redis::Promise`
+    class TimeoutError < Error; end
+
+    # Thrown when an awaited promise has been rejected.
+    class RejectedError < Error
+      #: untyped
+      attr_reader :value
+
+      #: (untyped) -> void
+      def initialize(value)
+        @value = value
+        super("rejected redis promise: #{value.inspect}")
+      end
+    end
+
+    class << self
+      # Create a pair of Promise and Resolver objects for the same key.
+      # The resolver can be used to either resolve or reject the promise.
+      # The promise can be used to wait for the result.
+      #
+      #: (Redis, ?id: String, ?namespace: String) -> [Promise, Resolver]
+      def create(redis, id: SecureRandom.uuid_v4, namespace: 'global')
+        key = "promise:#{namespace}:#{id}"
+
+        promise = Promise.new(redis, key: key)
+        resolver = Resolver.new(redis, key: key)
+
+        [promise, resolver]
+      end
+    end
+
+    #: Redis
+    attr_reader :redis
+
+    #: String
+    attr_reader :key
+
+    #: (Redis, ?id: String, ?namespace: String, ?key: String) -> void
+    def initialize(redis, id: SecureRandom.uuid_v4, namespace: 'global', key: "promise:#{namespace}:#{id}")
+      @redis = redis.dup #: Redis
+      @key = key
+    end
+
+    # Blocks the current thread until the resolved or rejected value
+    # is available. By default it blocks indefinitely.
+    # If the promise has been successfully resolved its value gets returned.
+    # If the promise has been rejected a `Redis::Promise::RejectedError` gets thrown.
+    #
+    # You can provide an optional `timeout:` argument that is a float
+    # of number of seconds the client should wait for the value.
+    # If the timeout is exceeded a `Redis::Promise::TimeoutError` is thrown.
+    #
+    #: (?timeout: Float | Integer) -> untyped
+    def await(timeout: 0)
+      result = @redis.blpop(@key, timeout: timeout)
+      raise TimeoutError unless result
+
+      parsed = JSON.parse(result[1], symbolize_names: true)
+
+      err = parsed[:err]
+      raise RejectedError.new(err) if err # rubocop:disable Style/RaiseArgs
+
+      parsed[:value]
+    end
+  end
+end

data/sorbet/config

@@ -0,0 +1,7 @@
+--dir
+.
+--enable-experimental-requires-ancestor
+--enable-experimental-rbs-comments
+--parser=prism
+--ignore=tmp/
+--ignore=vendor/

data/sorbet/rbi/annotations/.gitattributes

@@ -0,0 +1 @@
+**/*.rbi linguist-vendored=true

data/sorbet/rbi/annotations/minitest.rbi

@@ -0,0 +1,120 @@
+# typed: true
+
+# DO NOT EDIT MANUALLY
+# This file was pulled from a central RBI files repository.
+# Please run `bin/tapioca annotations` to update it.
+
+module Minitest::Assertions
+  sig { params(test: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert(test, msg = nil); end
+
+  sig { params(obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_empty(obj, msg = nil); end
+
+  sig { params(exp: T.anything, act: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_equal(exp, act, msg = nil); end
+
+  sig { params(exp: T.anything, act: T.anything, delta: Numeric, msg: T.anything).returns(TrueClass) }
+  def assert_in_delta(exp, act, delta = T.unsafe(nil), msg = nil); end
+
+  sig { params(a: T.anything, b: T.anything, epsilon: Numeric, msg: T.anything).returns(TrueClass) }
+  def assert_in_epsilon(a, b, epsilon = T.unsafe(nil), msg = nil); end
+
+  sig { params(collection: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_includes(collection, obj, msg = nil); end
+
+  sig { params(cls: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_instance_of(cls, obj, msg = nil); end
+
+  sig { params(cls: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_kind_of(cls, obj, msg = nil); end
+
+  sig { params(matcher: T.any(String, Regexp), obj: T.anything, msg: T.anything).returns(MatchData) }
+  def assert_match(matcher, obj, msg = nil); end
+
+  sig { params(obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_nil(obj, msg = nil); end
+
+  sig { params(o1: T.anything, op: T.any(Symbol, String), o2: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_operator(o1, op, o2 = T.unsafe(nil), msg = nil); end
+
+  sig { params(stdout: T.nilable(T.any(String, Regexp)), stderr: T.nilable(T.any(String, Regexp)), block: T.proc.void).returns(T::Boolean) }
+  def assert_output(stdout = nil, stderr = nil, &block); end
+
+  sig { params(path: T.any(String, Pathname), msg: T.anything).returns(TrueClass) }
+  def assert_path_exists(path, msg = nil); end
+
+  sig { params(block: T.proc.void).returns(TrueClass) }
+  def assert_pattern(&block); end
+
+  sig { params(o1: T.anything, op: T.any(String, Symbol), msg: T.anything).returns(TrueClass) }
+  def assert_predicate(o1, op, msg = nil); end
+
+  sig { params(exp: NilClass, block: T.proc.void).returns(StandardError) }
+  sig { type_parameters(:T).params(exp: T.any(T::Class[T.type_parameter(:T)], Regexp, String), block: T.proc.void).returns(T.type_parameter(:T)) }
+  def assert_raises(*exp, &block); end
+
+  sig { params(obj: T.anything, meth: T.any(String, Symbol), msg: T.anything, include_all: T::Boolean).returns(TrueClass) }
+  def assert_respond_to(obj, meth, msg = nil, include_all: false); end
+
+  sig { params(exp: T.anything, act: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_same(exp, act, msg = nil); end
+
+  # @version < 6.0.0
+  sig { params(send_ary: T::Array[T.anything], m: T.anything).returns(T::Boolean) }
+  def assert_send(send_ary, m = nil); end
+
+  sig { params(block: T.proc.void).returns(T::Boolean) }
+  def assert_silent(&block); end
+
+  sig { params(sym: Symbol, msg: T.anything, block: T.proc.void).returns(T.anything) }
+  def assert_throws(sym, msg = nil, &block); end
+
+  sig { params(test: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute(test, msg = nil); end
+
+  sig { params(obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_empty(obj, msg = nil); end
+
+  sig { params(exp: T.anything, act: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_equal(exp, act, msg = nil); end
+
+  sig { params(exp: T.anything, act: T.anything, delta: Numeric, msg: T.anything).returns(TrueClass) }
+  def refute_in_delta(exp, act, delta = T.unsafe(nil), msg = nil); end
+
+  sig { params(a: T.anything, b: T.anything, epsilon: Numeric, msg: T.anything).returns(TrueClass) }
+  def refute_in_epsilon(a, b, epsilon = T.unsafe(nil), msg = nil); end
+
+  sig { params(collection: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_includes(collection, obj, msg = nil); end
+
+  sig { params(cls: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_instance_of(cls, obj, msg = nil); end
+
+  sig { params(cls: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_kind_of(cls, obj, msg = nil); end
+
+  sig { params(matcher: T.any(String, Regexp), obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_match(matcher, obj, msg = nil); end
+
+  sig { params(obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_nil(obj, msg = nil); end
+
+  sig { params(block: T.proc.void).returns(TrueClass) }
+  def refute_pattern(&block); end
+
+  sig { params(o1: T.anything, op: T.any(Symbol, String), o2: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_operator(o1, op, o2 = T.unsafe(nil), msg = nil); end
+
+  sig { params(path: T.any(String, Pathname), msg: T.anything).returns(TrueClass) }
+  def refute_path_exists(path, msg = nil); end
+
+  sig { params(o1: T.anything, op: T.any(String, Symbol), msg: T.anything).returns(TrueClass) }
+  def refute_predicate(o1, op, msg = nil); end
+
+  sig { params(obj: T.anything, meth: T.any(String, Symbol), msg: T.anything, include_all: T::Boolean).returns(TrueClass) }
+  def refute_respond_to(obj, meth, msg = nil, include_all: false); end
+
+  sig { params(exp: T.anything, act: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_same(exp, act, msg = nil); end
+end