raktr 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2aa060f18df13540e73b42a5e9c68bdf86eaf03ae21104da0e827e57252dffe3
+  data.tar.gz: 5f1dd3fa7626e764f5212424c8e25b26a16bb52d4d00a2d2e6e4e5684575123a
+SHA512:
+  metadata.gz: 8889f36f41d78a38dbd5afb95af6f4c2836e2056bb00451dabb10141c19d34c1ce02a7809c54e3c807713ab0b3bb94e6d969eb423878ab2c8514db703c868f85
+  data.tar.gz: fa3426f952f1980e9916aeaa1af050da734fec2c8de94a8e352c5223271e4309f66abd9fba46399d5470394ad9b4d65801620c4b060e9b4db1c0775d23a8859e

data/CHANGELOG.md

@@ -0,0 +1 @@
+# ChangeLog

data/LICENSE.md

@@ -0,0 +1,29 @@
+# License
+
+    Copyright (C) 2022, Ecsypno <https://ecsypno.com/>
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without modification,
+    are permitted provided that the following conditions are met:
+
+        * Redistributions of source code must retain the above copyright notice,
+          this list of conditions and the following disclaimer.
+
+        * Redistributions in binary form must reproduce the above copyright notice,
+          this list of conditions and the following disclaimer in the documentation
+          and/or other materials provided with the distribution.
+
+        * Neither the name of the copyright holder nor the names of its contributors
+          may be used to endorse or promote products derived from this software
+          without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+    ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+    ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,77 @@
+# Raktr
+
+<table>
+    <tr>
+        <th>Version</th>
+        <td>0.0.1</td>
+    </tr>
+    <tr>
+        <th>Github page</th>
+        <td><a href="http://github.com/qadron/raktr">http://github.com/qadron/raktr</a></td>
+     <tr/>
+    <tr>
+        <th>Code Documentation</th>
+        <td><a href="http://rubydoc.info/github/qadron/raktr/">http://rubydoc.info/github/qadron/raktr/</a></td>
+    </tr>
+    <tr>
+       <th>Author</th>
+       <td><a href="http://twitter.com/Zap0tek">Tasos Laskos</a></td>
+    </tr>
+    <tr>
+        <th>Copyright</th>
+        <td>2022 <a href="https://ecsypno.com">Ecsypno</a></td>
+    </tr>
+    <tr>
+        <th>License</th>
+        <td><a href="file.LICENSE.html">3-clause BSD</a></td>
+    </tr>
+</table>
+
+## Synopsis
+
+Raktr is a simple, lightweight, pure-Ruby implementation of the
+[Reactor](http://en.wikipedia.org/wiki/Reactor_pattern) pattern, mainly focused
+on network connections -- and less so on generic tasks.
+
+## Features
+
+ - Extremely lightweight.
+ - Very simple design.
+ - Support for TCP/IP and UNIX-domain sockets.
+ - TLS encryption.
+ - Pure-Ruby.
+ - Multi-platform.
+
+## Supported platforms
+
+ - Rubies:
+    - MRI >= 1.9
+    - Rubinius
+    - JRuby
+ - Operating Systems:
+    - Linux
+    - OSX
+    - Windows
+
+## Examples
+
+For examples please see the `examples/` directory.
+
+## Installation
+
+    gem install raktr
+
+## Running the Specs
+
+    rake spec
+
+## Bug reports/Feature requests
+
+Please send your feedback using GitHub's issue system at
+[http://github.com/qadron/raktr/issues](http://github.com/qadron/raktr/issues).
+
+
+## License
+
+Raktr is provided under the 3-clause BSD license.
+See the [LICENSE](https://github.com/qadron/raktr/blob/master/LICENSE.md) file for more information.

data/Rakefile

@@ -0,0 +1,53 @@
+=begin
+
+    This file is part of the Raktr project and may be subject to
+    redistribution and commercial restrictions. Please see the Raktr
+    web site for more information on licensing and terms of use.
+
+=end
+
+require 'rubygems'
+require File.expand_path( File.dirname( __FILE__ ) ) + '/lib/raktr/version'
+
+begin
+    require 'rspec'
+    require 'rspec/core/rake_task'
+
+    RSpec::Core::RakeTask.new
+rescue
+end
+
+task default: [ :build, :spec ]
+
+desc 'Generate docs'
+task :docs do
+    outdir = '../raktr-docs'
+    sh "rm -rf #{outdir}"
+    sh "mkdir -p #{outdir}"
+
+    sh "yardoc -o #{outdir}"
+
+    sh 'rm -rf .yardoc'
+end
+
+desc 'Clean up'
+task :clean do
+    sh 'rm *.gem || true'
+end
+
+desc 'Build the gem.'
+task build: [ :clean ] do
+    sh "gem build raktr.gemspec"
+end
+
+desc 'Build and install the gem.'
+task install: [ :build ] do
+    sh "gem install raktr-#{Raktr::VERSION}.gem"
+end
+
+desc 'Push a new version to Rubygems'
+task publish: [ :build ] do
+    sh "git tag -a v#{Raktr::VERSION} -m 'Version #{Raktr::VERSION}'"
+    sh "gem push raktr-#{Raktr::VERSION}.gem"
+end
+task release: [ :publish ]

data/lib/raktr/connection/callbacks.rb

@@ -0,0 +1,71 @@
+=begin
+
+    This file is part of the Raktr project and may be subject to
+    redistribution and commercial restrictions. Please see the Raktr
+    web site for more information on licensing and terms of use.
+
+=end
+
+class Raktr
+class Connection
+
+# Callbacks to be invoked per event.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+module Callbacks
+
+    # Called after the connection has been established.
+    #
+    # @abstract
+    def on_connect
+    end
+
+    # Called after the connection has been attached to a {#raktr}.
+    #
+    # @abstract
+    def on_attach
+    end
+
+    # Called right the connection is detached from the {#raktr}.
+    #
+    # @abstract
+    def on_detach
+    end
+
+    # @note If a connection could not be established no {#socket} may be
+    #   available.
+    #
+    # Called when the connection gets closed.
+    #
+    # @param    [Exception] reason
+    #   Reason for the close.
+    #
+    # @abstract
+    def on_close( reason )
+    end
+
+    # Called when data are available.
+    #
+    # @param    [String] data
+    #   Incoming data.
+    #
+    # @abstract
+    def on_read( data )
+    end
+
+    # Called after each {#write} call.
+    #
+    # @abstract
+    def on_write
+    end
+
+    # Called after the {#write buffered data} have all been sent to the peer.
+    #
+    # @abstract
+    def on_flush
+    end
+
+end
+
+end
+end

data/lib/raktr/connection/error.rb

@@ -0,0 +1,120 @@
+=begin
+
+    This file is part of the Raktr project and may be subject to
+    redistribution and commercial restrictions. Please see the Raktr
+    web site for more information on licensing and terms of use.
+
+=end
+
+class Raktr
+class Connection
+
+# {Connection} error namespace.
+#
+# All {Connection} errors inherit from and live under it.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Error < Raktr::Error
+
+    class << self
+        # Captures Ruby exceptions and converts them to an appropriate
+        # subclass of {Error}.
+        #
+        # @param  [Block] block Block to run.
+        def translate( &block )
+            block.call
+        rescue IOError, Errno::ENOTCONN, Errno::ENOTSOCK => e
+            raise_with_proper_backtrace( e, Closed )
+        rescue SocketError, Errno::ENOENT => e
+            raise_with_proper_backtrace( e, HostNotFound )
+        rescue Errno::EPIPE => e
+            raise_with_proper_backtrace( e, BrokenPipe )
+        rescue Errno::ECONNREFUSED,
+            # JRuby throws Errno::EADDRINUSE when trying to connect to a
+            # non-existent server.
+            Errno::EADDRINUSE => e
+            raise_with_proper_backtrace( e, Refused )
+        rescue Errno::ECONNRESET, Errno::ECONNABORTED => e
+            raise_with_proper_backtrace( e, Reset )
+        rescue Errno::EACCES => e
+            raise_with_proper_backtrace( e, Permission )
+        rescue Errno::EBADF => e
+            raise_with_proper_backtrace( e, BadSocket )
+
+        # Catch and forward these before handling OpenSSL::OpenSSLError because
+        # all SSL errors inherit from it, including OpenSSL::SSL::SSLErrorWaitReadable
+        # and OpenSSL::SSL::SSLErrorWaitWritable which also inherit from
+        # IO::WaitReadable and IO::WaitWritable and need special treatment.
+        rescue IO::WaitReadable, IO::WaitWritable, Errno::EINPROGRESS
+            raise
+
+        # We're mainly interested in translating SSL handshake errors but there
+        # aren't any specific exceptions for these.
+        #
+        # Why make things easy and clean, right?
+        rescue OpenSSL::SSL::SSLError, OpenSSL::OpenSSLError => e
+            raise_with_proper_backtrace( e, SSL )
+        end
+
+        def raise_with_proper_backtrace( ruby, raktr )
+            e = raktr.new( ruby.to_s )
+            e.set_backtrace ruby.backtrace
+            raise e
+        end
+    end
+
+    # Like a `SocketError.getaddrinfo` exception.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class HostNotFound < Error
+    end
+
+    # Like a `Errno::EACCES` exception.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class Permission < Error
+    end
+
+    # Like a `Errno::ECONNREFUSED` exception.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class Refused < Error
+    end
+
+    # Like a `Errno::ECONNRESET` exception.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class Reset < Error
+    end
+
+    # Like a `Errno::EPIPE` exception.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class BrokenPipe < Error
+    end
+
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class Timeout < Error
+    end
+
+    # Like a `IOError` exception.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class Closed < Error
+    end
+
+    # Like a `Errno::EBADF` exception.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class BadSocket < Error
+    end
+
+    # Like a `OpenSSL::OpenSSLError` exception.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class SSL < Error
+    end
+
+end
+end
+end

data/lib/raktr/connection/peer_info.rb

@@ -0,0 +1,90 @@
+=begin
+
+    This file is part of the Raktr project and may be subject to
+    redistribution and commercial restrictions. Please see the Raktr
+    web site for more information on licensing and terms of use.
+
+=end
+
+class Raktr
+class Connection
+
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+module PeerInfo
+
+    # @param    [Bool]  resolve
+    #   Resolve IP address to hostname.
+    # @return   [Hash]
+    #   Peer address information:
+    #
+    #   * IP socket:
+    #       * Without `resolve`:
+    #
+    #               {
+    #                   protocol:   'AF_INET',
+    #                   port:       10314,
+    #                   hostname:   '127.0.0.1',
+    #                   ip_address: '127.0.0.1'
+    #               }
+    #
+    #       * With `resolve`:
+    #
+    #               {
+    #                   protocol:   'AF_INET',
+    #                   port:       10314,
+    #                   hostname:   'localhost',
+    #                   ip_address: '127.0.0.1'
+    #               }
+    #
+    #   * UNIX-domain socket:
+    #
+    #           {
+    #               protocol: 'AF_UNIX',
+    #               path:     '/tmp/my-socket'
+    #           }
+    def peer_address_info( resolve = false )
+        if Raktr.supports_unix_sockets? && to_io.is_a?( UNIXSocket )
+            {
+                protocol: to_io.peeraddr.first,
+                path:     to_io.path
+            }
+        else
+            protocol, port, hostname, ip_address = to_io.peeraddr( resolve )
+
+            {
+                protocol:   protocol,
+                port:       port,
+                hostname:   hostname,
+                ip_address: ip_address
+            }
+        end
+    end
+
+    # @return   [String]
+    #   Peer's IP address or socket path.
+    def peer_address
+        peer_ip_address || peer_address_info[:path]
+    end
+
+    # @return   [String]
+    #   Peer's IP address.
+    def peer_ip_address
+        peer_address_info[:ip_address]
+    end
+
+    # @return   [String]
+    #   Peer's hostname.
+    def peer_hostname
+        peer_address_info(true)[:hostname]
+    end
+
+    # @return   [String]
+    #   Peer's port.
+    def peer_port
+        peer_address_info[:port]
+    end
+
+end
+
+end
+end

data/lib/raktr/connection/tls.rb

@@ -0,0 +1,164 @@
+=begin
+
+    This file is part of the Raktr project and may be subject to
+    redistribution and commercial restrictions. Please see the Raktr
+    web site for more information on licensing and terms of use.
+
+=end
+
+class Raktr
+class Connection
+
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+module TLS
+
+    # Converts the {#socket} to an SSL one.
+    #
+    # @param    [Hash]  options
+    # @option   [String]    :certificate
+    #   Path to a PEM certificate.
+    # @option   [String]    :private_key
+    #   Path to a PEM private key.
+    # @option   [String]    :ca
+    #   Path to a PEM CA.
+    def start_tls( options = {} )
+        if @socket.is_a? OpenSSL::SSL::SSLSocket
+            @ssl_context = @socket.context
+            return
+        end
+
+        @ssl_context = OpenSSL::SSL::SSLContext.new
+        @ssl_context.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+        if options[:certificate] && options[:private_key]
+
+            @ssl_context.cert =
+                OpenSSL::X509::Certificate.new( File.open( options[:certificate] ) )
+            @ssl_context.key  =
+                OpenSSL::PKey::RSA.new( File.open( options[:private_key] ) )
+
+            @ssl_context.ca_file     = options[:ca]
+            @ssl_context.verify_mode =
+                OpenSSL::SSL::VERIFY_PEER | OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT
+
+        elsif @role == :server
+            @ssl_context.key             = OpenSSL::PKey::RSA.new( 2048 )
+            @ssl_context.cert            = OpenSSL::X509::Certificate.new
+            @ssl_context.cert.subject    = OpenSSL::X509::Name.new( [['CN', 'localhost']] )
+            @ssl_context.cert.issuer     = @ssl_context.cert.subject
+            @ssl_context.cert.public_key = @ssl_context.key
+            @ssl_context.cert.not_before = Time.now
+            @ssl_context.cert.not_after  = Time.now + 60 * 60 * 24
+            @ssl_context.cert.version    = 2
+            @ssl_context.cert.serial     = 1
+
+            @ssl_context.cert.sign( @ssl_context.key, OpenSSL::Digest::SHA1.new )
+        end
+
+        if @role == :server
+            @socket = OpenSSL::SSL::SSLServer.new( @socket, @ssl_context )
+        else
+            @socket = OpenSSL::SSL::SSLSocket.new( @socket, @ssl_context )
+            @socket.sync_close = true
+
+            # We've switched to SSL, a connection needs to be re-established
+            # via the SSL handshake.
+            @connected         = false
+
+            _connect if unix?
+        end
+
+        @socket
+    end
+
+    # Performs an SSL handshake in addition to a plaintext connect operation.
+    #
+    # @private
+    def _connect
+        return if @ssl_connected
+
+        Error.translate do
+            @plaintext_connected ||= super
+            return if !@plaintext_connected
+
+            # Mark the connection as not connected due to the pending SSL handshake.
+            @connected = false
+
+            @socket.connect_nonblock
+            @ssl_connected = @connected = true
+        end
+    rescue IO::WaitReadable, IO::WaitWritable, Errno::EINPROGRESS
+    rescue Error => e
+        close e
+    end
+
+    # First checks if there's a pending SSL #accept operation when this
+    # connection is a server handler which has been passed an accepted
+    # plaintext connection.
+    #
+    # @private
+    def _write( *args )
+        return ssl_accept if accept?
+
+        super( *args )
+    end
+
+    # First checks if there's a pending SSL #accept operation when this
+    # connection is a server handler which has been passed an accepted
+    # plaintext connection.
+    #
+    # @private
+    def _read
+        return ssl_accept if accept?
+
+        super
+    rescue OpenSSL::SSL::SSLErrorWaitReadable
+    end
+
+    private
+
+    def ssl_accept
+        Error.translate do
+            @accepted = !!@socket.accept_nonblock
+        end
+    rescue IO::WaitReadable, IO::WaitWritable
+    rescue Error => e
+        close e
+        false
+    end
+
+    def accept?
+        return false if @accepted
+        return false if role != :server || !@socket.is_a?( OpenSSL::SSL::SSLSocket )
+
+        true
+    end
+
+    # Accepts a new SSL client connection.
+    #
+    # @return   [OpenSSL::SSL::SSLSocket, nil]
+    #   New connection or `nil` if the socket isn't ready to accept new
+    #   connections yet.
+    #
+    # @private
+    def socket_accept
+        Error.translate do
+            socket = to_io.accept_nonblock
+
+            ssl_socket = OpenSSL::SSL::SSLSocket.new(
+                socket,
+                @ssl_context
+            )
+            ssl_socket.sync_close = true
+            ssl.accept if @start_immediately
+            ssl_socket
+        end
+    rescue IO::WaitReadable, IO::WaitWritable
+    rescue Error => e
+        close e
+    end
+
+end
+
+end
+end