kstor 0.4.3 → 0.5.0

data/lib/kstor/message.rb

@@ -3,130 +3,43 @@
 require 'json'
 
 module KStor
-  # Internal exception when a request is received with neither a session ID nor
-  # a login/password pair.
-  #
-  # We can't use a KStor::Error here because kstor/error.rb require()s
-  # kstor/message.rb .
-  class RequestMissesAuthData < RuntimeError
-  end
-
-  class UnparsableResponse < RuntimeError
-  end
-
-  # A user request or response.
-  class Message
-    attr_reader :type
-    attr_reader :args
-
-    def initialize(type, args)
-      @type = type
-      @args = args
-    end
-
-    def to_h
-      { 'type' => @type, 'args' => @args }
-    end
-
-    def serialize
-      to_h.to_json
-    end
-
-    # Parse a user request, freshly arrived from the network.
+  module Message
+    # Internal exception when a request is received with neither a session ID
+    # nor a login/password pair.
     #
-    # @param str [String] serialized request
-    # @return [LoginRequest,SessionRequest] a request
-    # @raise [KStor::RequestMissesAuthData]
-    def self.parse_request(str)
-      data = JSON.parse(str)
-      if data.key?('login') && data.key?('password')
-        LoginRequest.new(
-          data['login'], data['password'],
-          data['type'], data['args']
-        )
-      elsif data.key?('session_id')
-        SessionRequest.new(
-          data['session_id'], data['type'], data['args']
-        )
-      else
-        raise RequestMissesAuthData
-      end
-    end
-  end
-
-  # A user authentication request.
-  class LoginRequest < Message
-    attr_reader :login
-    attr_reader :password
-
-    def initialize(login, password, type, args)
-      @login = login
-      @password = password
-      super(type, args)
-    end
-
-    def inspect
-      fmt = [
-        '#<KStor::LoginRequest:%<id>x',
-        '@login=%<login>s',
-        '@password="******"',
-        '@args=%<args>s>'
-      ].join(' ')
-      format(fmt, id: object_id, login: @login.inspect, args: @args.inspect)
+    # We can't use a KStor::Error here because kstor/error.rb require()s
+    # kstor/message.rb .
+    class RequestMissesAuthData < RuntimeError
     end
 
-    def to_h
-      super.merge('login' => @login, 'password' => @password)
+    # Response data was invalid JSON.
+    class UnparsableResponse < RuntimeError
     end
   end
+end
 
-  # A user request with a session ID.
-  class SessionRequest < Message
-    attr_reader :session_id
+require 'kstor/message/error'
 
-    def initialize(session_id, type, args)
-      @session_id = session_id
-      super(type, args)
-    end
+require 'kstor/message/ping'
+require 'kstor/message/pong'
 
-    def inspect
-      fmt = [
-        '#<KStor::SessionRequest:%<id>x',
-        '@session_id=******',
-        '@args=%<args>s>'
-      ].join(' ')
-      format(fmt, id: object_id, args: @args.inspect)
-    end
+require 'kstor/message/group_create'
+require 'kstor/message/group_created'
 
-    def to_h
-      super.merge('session_id' => @session_id)
-    end
-  end
+require 'kstor/message/secret_create'
+require 'kstor/message/secret_created'
 
-  # Response to a user request.
-  class Response < Message
-    attr_accessor :session_id
+require 'kstor/message/secret_delete'
+require 'kstor/message/secret_deleted'
 
-    def initialize(type, args)
-      @session_id = nil
-      super
-    end
+require 'kstor/message/secret_search'
+require 'kstor/message/secret_list'
 
-    def self.parse(str)
-      data = JSON.parse(str)
-      resp = new(data['type'], data['args'])
-      resp.session_id = data['session_id']
-      resp
-    rescue JSON::ParserError => e
-      raise UnparsableResponse, e.message
-    end
+require 'kstor/message/secret_unlock'
+require 'kstor/message/secret_value'
 
-    def error?
-      @type == 'error'
-    end
+require 'kstor/message/secret_update_meta'
+require 'kstor/message/secret_update_value'
+require 'kstor/message/secret_updated'
 
-    def to_h
-      super.merge('session_id' => @session_id)
-    end
-  end
-end
+KStor::Message.register_all_message_types

data/lib/kstor/model.rb

@@ -86,10 +86,7 @@ module KStor
 
       # Dump properties except pubk.
       def to_h
-        h = super
-        h.delete('pubk')
-
-        h
+        super.except('pubk')
       end
     end
 
@@ -154,9 +151,7 @@ module KStor
 
       # Dump properties except {#encrypted_privk}.
       def to_h
-        h = super
-        h.delete('encrypted_privk')
-        h
+        super.except('encrypted_privk')
       end
     end
 
@@ -263,9 +258,6 @@ module KStor
         self.kdf_params = secret_key.kdf_params
         encrypt(secret_key)
         self.keychain = {}
-        # FIXME: delete keychain items from database!
-        #   they won't be useable (decryption key is lost) but will provoke
-        #   errors.
       end
 
       # Re-encrypt private key and keychain with a new secret key derived from
@@ -283,9 +275,7 @@ module KStor
 
       # Dump properties except {#encrypted_privk} and {#pubk}.
       def to_h
-        h = super
-        h.delete('encrypted_privk')
-        h.delete('pubk')
+        h = super.except('encrypted_privk', 'pubk')
         h['keychain'] = keychain.transform_values(&:to_h) if keychain
 
         h
@@ -320,6 +310,13 @@ module KStor
       # Secret should be used at this URL
       attr_accessor :url
 
+      # Create new metadata for a secret.
+      #
+      # Hash param can contains keys for "app", "database", "login", "server"
+      # and "url". Any other key is ignored.
+      #
+      # @param values [Hash, KStor::Crypto::ArmoredHash] metadata
+      # @return [KStor::Model::SecretMeta] secret metadata
       def initialize(values)
         @app = values['app']
         @database = values['database']
@@ -328,30 +325,50 @@ module KStor
         @url = values['url']
       end
 
+      # Convert this metadata to a Hash.
+      #
+      # Empty values will not be included.
+      #
+      # @return [Hash[String, String]] metadata as a Hash
       def to_h
         { 'app' => @app, 'database' => @database, 'login' => @login,
           'server' => @server, 'url' => @url }.compact
       end
 
+      # Prepare metadata to be written to disk or database.
+      #
+      # @return [KStor::Crypto::ArmoredHash] serialized metadata
       def serialize
         Crypto::ArmoredHash.from_hash(to_h)
       end
 
+      # Merge metadata.
+      #
+      # @param other [KStor::Model::SecretMeta] other metadata that will
+      #   override this object's values.
       def merge(other)
         values = to_h.merge(other.to_h)
         values.reject! { |_, v| v.empty? }
         self.class.new(values)
       end
 
-      def self.load(armored_hash)
-        new(armored_hash.to_hash)
-      end
-
+      # Match against wildcards.
+      #
+      # Metadata will be matched against another metadata object with wildcard
+      # values. This uses roughly the same rules that shell wildcards (e.g.
+      # fnmatch(3) C function).
+      #
+      # @see File.fnmatch?
+      #
+      # @param meta [KStor::Model::SecretMeta] wildcard metadata
+      # @return [Boolean] true if matched
+      # rubocop:disable Metrics/CyclomaticComplexity
       def match?(meta)
         self_h = to_h
         other_h = meta.to_h
         other_h.each do |k, wildcard|
           val = self_h[k]
+          return false if val.nil? && !wildcard.nil? && wildcard != '*'
           next if val.nil?
           next if wildcard.nil?
 
@@ -362,6 +379,7 @@ module KStor
         end
         true
       end
+      # rubocop:enable Metrics/CyclomaticComplexity
     end
 
     # A secret, with metadata and a value that are kept encrypted on disk.
@@ -383,8 +401,11 @@ module KStor
       # @!macro dsl_model_properties_rw
       property :metadata, read_only: true
 
+      # Set metadata (or unset if nil).
+      #
+      # @param armored_hash [KStor::Crypt::ArmoredHash] metadata to load
       def metadata=(armored_hash)
-        @data[:metadata] = armored_hash ? SecretMeta.load(armored_hash) : nil
+        @data[:metadata] = armored_hash ? SecretMeta.new(armored_hash) : nil
       end
 
       # Decrypt secret value.
@@ -424,13 +445,9 @@ module KStor
       # Dump properties except {#ciphertext}, {#encrypted_metadata},
       # {#value_author_id} and {#meta_author_id}.
       def to_h
-        h = super
-        h.delete('ciphertext')
-        h.delete('encrypted_metadata')
-        h.delete('value_author_id')
-        h.delete('meta_author_id')
-
-        h
+        super.except(
+          *%w[ciphertext encrypted_metadata value_author_id meta_author_id]
+        )
       end
     end
   end

data/lib/kstor/server.rb

@@ -15,11 +15,24 @@ module KStor
 
   # Listen for clients and respond to their requests.
   class Server < SocketServer
+    # Create a new server object.
+    #
+    # @param controller [KStor::Controller::RequestHandler] client request
+    #   handler
+    # @param args [Hash] parameters to apss to parent class
+    #   {KStor::SocketServer}
+    # @return [KStor::Server] new KStor server.
     def initialize(controller:, **args)
       @controller = controller
       super(**args)
     end
 
+    # Implement {KStor::SocketServer#work} to actually serve clients.
+    #
+    # This method must read client request, write a response and close the
+    # socket.
+    #
+    # @param client [Socket] channel of communication to a client
     def work(client)
       client_data, = client.recvfrom(4096)
       Log.debug("server: read #{client_data.bytesize} bytes from client")
@@ -36,15 +49,14 @@ module KStor
     private
 
     def handle_client_data(data)
-      req = Message.parse_request(data)
+      req = Message::Base.parse(data)
       resp = @controller.handle_request(req)
-      Log.debug("server: response = #{resp.inspect}")
       resp.serialize
     rescue JSON::ParserError => e
       err = Error.for_code('MSG/INVALID', e.message)
       Log.info("server: #{err}")
       err.response.serialize
-    rescue RequestMissesAuthData
+    rescue Message::RequestMissesAuthData
       raise Error.for_code('MSG/INVALID', 'Missing authentication data')
     end
   end

data/lib/kstor/session.rb

@@ -11,6 +11,13 @@ module KStor
     attr_reader :created_at
     attr_reader :updated_at
 
+    # Create a new user session.
+    #
+    # @param sid [String] Session ID
+    # @param user [KStor::Model::User] user owning the session
+    # @param secret_key [KStor::Crypto::SecretKey] user secret key, derived
+    #   from password
+    # @return [KStor::Session] new session
     def initialize(sid, user, secret_key)
       @id = sid
       @user = user
@@ -19,21 +26,37 @@ module KStor
       @updated_at = Time.now
     end
 
+    # Update access time, for idle sessions weeding.
+    #
+    # @return [KStor::Session] updated session
     def update
       @updated_at = Time.now
       self
     end
 
+    # Create a new session for a user.
+    #
+    # @param user [KStor::Model::User] user owning the session
+    # @param secret_key [KStor::Crypto::SecretKey] user secret key, derived
+    #   from password
+    # @return [KStor::Session] new session with a random SID
     def self.create(user, secret_key)
       sid = SecureRandom.urlsafe_base64(16)
       new(sid, user, secret_key)
     end
   end
 
-  # Collection of user sessions (in memory)
+  # Collection of user sessions (in memory).
   #
-  # FIXME make it thread safe!
+  # Concurrent accesses are synchronized on a mutex.
   class SessionStore
+    # Create new session store.
+    #
+    # @param idle_timeout [Integer] sessions that aren't updated for this
+    #   number of seconds are considered invalid
+    # @param life_timeout [Integer] sessions that are older than this number of
+    #   seconds are considered invalid
+    # @return [KStor::SessionStore] a new session store.
     def initialize(idle_timeout, life_timeout)
       @idle_timeout = idle_timeout
       @life_timeout = life_timeout
@@ -41,12 +64,20 @@ module KStor
       @sessions.extend(Mutex_m)
     end
 
+    # Add a session to the store.
+    #
+    # @param session [KStor::Session] session to store
     def <<(session)
       @sessions.synchronize do
         @sessions[session.id] = session
       end
     end
 
+    # Fetch a session from it's ID.
+    #
+    # @param sid [String] session ID to lookup
+    # @return [KStor::Session, nil] session or nil if session ID was not found
+    #   or session has expired
     def [](sid)
       @sessions.synchronize do
         s = @sessions[sid.to_s]
@@ -61,6 +92,7 @@ module KStor
       end
     end
 
+    # Delete expired sessions.
     def purge
       now = Time.now
       @sessions.synchronize do

data/lib/kstor/socket_server.rb

@@ -9,8 +9,14 @@ require 'timeout'
 module KStor
   # Serve clients on UNIX sockets.
   class SocketServer
+    # Wait this number of seconds for worker threads to terminate before
+    # killing them without mercy.
     GRACEFUL_TIMEOUT = 10
 
+    # Create a new server.
+    #
+    # @param socket_path [String] path to listening socket
+    # @param nworkers [Integer] number of worker threads
     def initialize(socket_path:, nworkers:)
       @path = socket_path
       @nworkers = nworkers
@@ -18,10 +24,14 @@ module KStor
       @workers = []
     end
 
+    # Start serving clients.
+    #
+    # Send interrupt signal to cleanly stop.
     def start
       start_workers
-      server = Systemd.socket
+      server = server_socket
       Systemd.service_ready
+      Log.info('socket_server: started')
       loop do
         maintain_workers
         @client_queue.enq(server.accept.first)
@@ -31,6 +41,8 @@ module KStor
       Log.info('socket_server: stopped.')
     end
 
+    # Do some work for a client and write a response.
+    # @abstract
     def work(client)
       # Abstract method.
       client.close
@@ -38,6 +50,13 @@ module KStor
 
     private
 
+    def server_socket
+      s = Systemd.socket
+      return s if s
+
+      UNIXServer.new(@path)
+    end
+
     def worker_run
       while (client = @client_queue.deq)
         Log.debug("socket_server: #{Thread.current.name} serving one client")

data/lib/kstor/sql_connection.rb

@@ -14,18 +14,33 @@ module KStor
 
   # Execute SQL commands in a per-thread SQLite connection.
   class SQLConnection
+    # Create a new SQL connection.
+    #
+    # @param file_path [String] path to SQLite database
+    # @return [KStor::SQLConnection] the new connection
     def initialize(file_path)
       @file_path = file_path
     end
 
+    # Execute SQL statement.
+    #
+    # @param sql [String] SQL statement
+    # @param params [Array] parameters to fill placeholders in the statement
+    # @return [Any] Whatever SQLite returns
     def execute(sql, *params, &)
       database.execute(sql, *params, &)
     end
 
+    # Last generated ID (from an INSERT statement).
+    #
+    # @return [Integer] generated ID from last insert statement.
     def last_insert_row_id
       database.last_insert_row_id
     end
 
+    # Execute given block of code in a database transaction.
+    #
+    # @return [Any] Whatever the block returns
     def transaction(&block)
       result = nil
       database.transaction do |db|
@@ -52,7 +67,7 @@ module KStor
     def setup_thread_connection(key)
       return if Thread.current[key]
 
-      Log.info(
+      Log.debug(
         "sqlite: initializing connection in thread #{Thread.current.name}"
       )
       Thread.current[key] = connect(@file_path)