realtimex 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 248492f88d791add118caa113b362ba09278d11a0dca554adc605f797146c2bd
+  data.tar.gz: 4014a8f1e9476b8c88ce36235444f36110c793585ea06ac8b1bed6abecc113b1
+SHA512:
+  metadata.gz: 5e5b7ebff0ddca610032838935773e8e68f680772c922ac4fdf5c0228dfaeab968ea073dddc7d1dc2d2fda136db0f747f2f7c381b7707718a37a40f929d5991c
+  data.tar.gz: a154dbde5fb2fb30f686fd912d9a19a0655d345ceffa104310088e367d71c943aaac403b63f37dbdd48ef8867bbe25f7faa1530b47405982593633d7eb960b23

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RealtimeX
+
+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,202 @@
+# RealtimeX Ruby SDK
+
+Ruby client library for RealtimeX real-time messaging service.
+
+## Installation
+
+### Gemfile
+```ruby
+gem 'socketio-client-simple', '~> 1.2'
+gem 'json', '~> 2.0'
+```
+
+### Manual
+```bash
+gem install socketio-client-simple json
+```
+
+## Quick Start
+
+```ruby
+require_relative 'lib/realtimex'
+
+# Initialize
+realtimex = RealtimeX.new('YOUR_API_KEY', {
+  ws_host: 'localhost',
+  ws_port: 3001,
+  encrypted: false
+})
+
+# Connect
+realtimex.connect
+
+# Subscribe to a channel
+channel = realtimex.subscribe('my-channel')
+
+# Listen for events
+channel.bind('my-event') do |data|
+  puts "Received: #{data}"
+end
+
+# Send client events
+channel.trigger('client-my-event', {
+  message: 'Hello'
+})
+```
+
+## API Reference
+
+### RealtimeX
+
+#### Constructor
+```ruby
+realtimex = RealtimeX.new(api_key, options)
+```
+
+**Parameters:**
+- `api_key` (String): Your RealtimeX API key
+- `options` (Hash, optional): Configuration options
+  - `:ws_host` (String): WebSocket host, default 'localhost'
+  - `:ws_port` (Integer): WebSocket port, default 3001
+  - `:encrypted` (Boolean): Use WSS, default false
+
+#### Methods
+
+**connect**
+```ruby
+realtimex.connect
+```
+
+**subscribe(channel_name)**
+```ruby
+channel = realtimex.subscribe('my-channel')
+private_channel = realtimex.subscribe('private-my-channel')
+```
+
+**disconnect**
+```ruby
+realtimex.disconnect
+```
+
+### Channel
+
+#### Methods
+
+**bind(event, &block)**
+```ruby
+channel.bind('my-event') do |data|
+  puts "Event data: #{data}"
+end
+```
+
+**trigger(event, data)**
+```ruby
+# Client events must start with 'client-'
+channel.trigger('client-my-event', {
+  message: 'Hello World'
+})
+```
+
+### Connection Events
+
+```ruby
+realtimex.connection.bind('connected') do
+  puts 'Connected to RealtimeX'
+end
+
+realtimex.connection.bind('disconnected') do
+  puts 'Disconnected from RealtimeX'
+end
+```
+
+## Channel Types
+
+### Public Channels
+```ruby
+channel = realtimex.subscribe('my-channel')
+```
+
+### Private Channels
+```ruby
+private_channel = realtimex.subscribe('private-my-channel')
+```
+
+## WebSocket Protocol
+
+### Connection
+```
+ws://your-host:port/socket.io/?EIO=4&transport=websocket&api_key=YOUR_API_KEY
+```
+
+### Message Format
+
+**Subscribe:**
+```json
+{
+  "event": "realtimex:subscribe",
+  "data": {
+    "channel": "my-channel"
+  }
+}
+```
+
+**Client Event:**
+```json
+{
+  "event": "client-event",
+  "data": {
+    "channel": "my-channel",
+    "event": "client-my-event",
+    "data": { "message": "Hello" }
+  }
+}
+```
+
+**Server Event:**
+```json
+{
+  "event": "server-event",
+  "data": {
+    "event": "my-event",
+    "channel": "my-channel",
+    "data": { "message": "Hello" }
+  }
+}
+```
+
+## Compatibility
+
+### Ruby Support
+- Ruby 2.7+
+- JRuby 9.3+
+- TruffleRuby 22+
+
+### Dependencies
+- `socketio-client-simple` ~> 1.2
+- `json` ~> 2.0
+
+## Features
+
+✅ WebSocket connection management  
+✅ Channel subscription/unsubscription  
+✅ Event listening and triggering  
+✅ Client events  
+✅ YARD documentation  
+✅ Unit tests with RSpec  
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Generate documentation
+yardoc
+```
+
+## License
+
+MIT

data/lib/realtimex/channel.rb

@@ -0,0 +1,29 @@
+# Channel for handling real-time events
+class RealtimeX::Channel
+  attr_reader :name
+
+  def initialize(name, client)
+    @name = name
+    @client = client
+    @callbacks = {}
+  end
+
+  # Send client event to channel
+  # @param event [String] Event name (must start with 'client-')
+  # @param data [Hash] Event data
+  def trigger(event, data)
+    raise "Event must start with 'client-'" unless event.start_with?('client-')
+    @client.connection.send_client_event(@name, event, data)
+  end
+
+  # Bind callback to event
+  # @param event [String] Event name to listen for
+  # @param block [Proc] Callback to execute
+  def bind(event, &block)
+    @callbacks[event] = block
+  end
+
+  def handle_event(event, data)
+    @callbacks[event]&.call(data)
+  end
+end

data/lib/realtimex/channel_manager.rb

@@ -0,0 +1,24 @@
+# Manages channel subscriptions and message routing
+class RealtimeX::ChannelManager
+  def initialize
+    @channels = {}
+  end
+
+  def get_existing(channel_name)
+    @channels[channel_name]
+  end
+
+  def create(channel_name, client)
+    channel = RealtimeX::Channel.new(channel_name, client)
+    @channels[channel_name] = channel
+    channel
+  end
+
+  def route_message(message)
+    channel_name = message['channel']
+    event = message['event']
+    data = message['data']
+    
+    @channels[channel_name]&.handle_event(event, data)
+  end
+end

data/lib/realtimex/connection.rb

@@ -0,0 +1,60 @@
+require 'socket.io-client-simple'
+
+class RealtimeX::Connection
+  def initialize(url)
+    @url = url
+    @socket = nil
+    @callbacks = {}
+  end
+
+  def connect
+    @socket = SocketIO::Client::Simple.connect(@url, transports: ['websocket'])
+    setup_handlers
+  end
+
+  def setup_handlers
+    @socket.on :connect do
+      emit('connected')
+    end
+    
+    @socket.on :disconnect do
+      emit('disconnected')
+    end
+    
+    @socket.on 'server-event' do |data|
+      emit('message', data)
+    end
+
+    @socket.on 'realtimex_internal:subscription_succeeded' do |data|
+      emit('subscription_succeeded', data)
+    end
+  end
+
+  def send_subscribe(channel)
+    @socket.emit('realtimex:subscribe', { channel: channel })
+  end
+
+  def send_client_event(channel, event, data)
+    @socket.emit('client-event', {
+      channel: channel,
+      event: event,
+      data: data
+    })
+  end
+
+  def send_unsubscribe(channel)
+    @socket.emit('realtimex:unsubscribe', { channel: channel })
+  end
+
+  def bind(event, &block)
+    @callbacks[event] = block
+  end
+
+  def emit(event, data = nil)
+    @callbacks[event]&.call(data)
+  end
+
+  def disconnect
+    @socket&.disconnect
+  end
+end

data/lib/realtimex/version.rb

@@ -0,0 +1,3 @@
+class RealtimeX
+  VERSION = "1.0.1"
+end

data/lib/realtimex.rb

@@ -0,0 +1,74 @@
+require_relative 'realtimex/version'
+require_relative 'realtimex/connection'
+require_relative 'realtimex/channel'
+require_relative 'realtimex/channel_manager'
+
+# RealtimeX Ruby SDK for real-time messaging
+class RealtimeX
+  attr_reader :connection
+
+  # Initialize RealtimeX client
+  # @param api_key [String] API key for authentication
+  # @param options [Hash] Connection options
+  # @option options [String] :ws_host WebSocket host (default: 'localhost')
+  # @option options [Integer] :ws_port WebSocket port (default: 3001)
+  # @option options [Boolean] :encrypted Use HTTPS/WSS (default: false)
+  def initialize(api_key, options = {})
+    @api_key = api_key
+    @options = default_options.merge(options)
+    @channel_manager = ChannelManager.new
+    
+    url = build_url
+    @connection = RealtimeX::Connection.new(url)
+    setup_connection_handlers
+  end
+
+  # Establish WebSocket connection
+  def connect
+    @connection.connect
+  end
+
+  # Subscribe to a channel
+  # @param channel_name [String] Channel name to subscribe to
+  # @return [RealtimeX::Channel] Channel instance
+  def subscribe(channel_name)
+    existing = @channel_manager.get_existing(channel_name)
+    return existing if existing
+    
+    channel = @channel_manager.create(channel_name, self)
+    @connection.send_subscribe(channel_name)
+    channel
+  end
+
+  # Disconnect from WebSocket
+  def disconnect
+    @connection.disconnect
+  end
+
+  private
+
+  def default_options
+    {
+      ws_host: 'localhost',
+      ws_port: 3001,
+      encrypted: false
+    }
+  end
+
+  def build_url
+    protocol = @options[:encrypted] ? 'https' : 'http'
+    host = @options[:ws_host]
+    port = @options[:ws_port]
+    "#{protocol}://#{host}:#{port}/socket.io/?EIO=4&transport=websocket&api_key=#{@api_key}"
+  end
+
+  def setup_connection_handlers
+    @connection.bind('message') do |data|
+      route_to_channel(data)
+    end
+  end
+
+  def route_to_channel(message)
+    @channel_manager.route_message(message)
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: realtimex
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- RealtimeX Team
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-12-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: socket.io-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: RealtimeX Ruby SDK provides WebSocket-based real-time messaging with
+  channels, events, and client-server communication
+email:
+- support@realtimex.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/realtimex.rb
+- lib/realtimex/channel.rb
+- lib/realtimex/channel_manager.rb
+- lib/realtimex/connection.rb
+- lib/realtimex/version.rb
+homepage: https://github.com/realtimex/realtimex-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Ruby client library for RealtimeX real-time messaging service
+test_files: []