systemd-journal 1.0.2 → 1.1.0

data/lib/systemd/journal/native.rb

@@ -1,7 +1,9 @@
+require 'systemd/id128'
+
 module Systemd
   class Journal
     # Provides the FFI bindings to the native `libsystemd-journal` shared
-    #  library.
+    # library.
     module Native
       # rubocop:disable LineLength
       require 'ffi'
@@ -31,6 +33,8 @@ module Systemd
       attach_function :sd_journal_get_data,       [:pointer, :string, :pointer, :pointer], :int
       attach_function :sd_journal_restart_data,   [:pointer], :void
       attach_function :sd_journal_enumerate_data, [:pointer, :pointer, :pointer], :int
+      attach_function :sd_journal_get_catalog,    [:pointer, :pointer], :int
+      attach_function :sd_journal_get_catalog_for_message_id, [Systemd::Id128::Native::Id128.by_value, :pointer], :int
 
       attach_function :sd_journal_get_data_threshold, [:pointer, :pointer], :int
       attach_function :sd_journal_set_data_threshold, [:pointer, :size_t],  :int
@@ -41,12 +45,11 @@ module Systemd
       attach_function :sd_journal_restart_unique,   [:pointer], :void
 
       # event notification
-      enum :wake_reason, [
-        :nop,
-        :append,
-        :invalidate
-      ]
+      enum            :wake_reason,     [:nop, :append, :invalidate]
       attach_function :sd_journal_wait, [:pointer, :uint64], :wake_reason, blocking: true
+      attach_function :sd_journal_get_fd,      [:pointer], :int
+      attach_function :sd_journal_process,     [:pointer], :wake_reason
+      attach_function :sd_journal_reliable_fd, [:pointer], :int
 
       # filtering
       attach_function :sd_journal_add_match,       [:pointer, :string, :size_t], :int

data/lib/systemd/journal/navigable.rb

@@ -0,0 +1,112 @@
+module Systemd
+  class Journal
+    module Navigable
+      # returns a string representing the current read position.
+      # This string can be passed to {#seek} or {#cursor?}.
+      # @return [String] a cursor token.
+      def cursor
+        out_ptr = FFI::MemoryPointer.new(:pointer, 1)
+        if (rc = Native.sd_journal_get_cursor(@ptr, out_ptr)) < 0
+          raise JournalError.new(rc)
+        end
+
+        Journal.read_and_free_outstr(out_ptr.read_pointer)
+      end
+
+      # Check if the read position is currently at the entry represented by the
+      # provided cursor value.
+      # @param c [String] a cursor token returned from {#cursor}.
+      # @return [Boolean] True if current entry is the one represented by the
+      # provided cursor, False otherwise.
+      def cursor?(c)
+        if (rc = Native.sd_journal_test_cursor(@ptr, c)) < 0
+          raise JournalError.new(rc)
+        end
+
+        rc > 0
+      end
+
+      # Move the read pointer by `offset` entries.
+      # @param [Integer] offset how many entries to move the read pointer by.
+      #   If this value is positive, the read pointer moves forward. Otherwise,
+      #   it moves backwards.
+      # @return [Integer] number of entries the read pointer actually moved.
+      def move(offset)
+        offset > 0 ? move_next_skip(offset) : move_previous_skip(-offset)
+      end
+
+      # Move the read pointer to the next entry in the journal.
+      # @return [Boolean] True if moving to the next entry was successful.
+      # @return [Boolean] False if unable to move to the next entry, indicating
+      #   that the pointer has reached the end of the journal.
+      def move_next
+        rc = Native.sd_journal_next(@ptr)
+        raise JournalError.new(rc) if rc < 0
+        rc > 0
+      end
+
+      # Move the read pointer forward by `amount` entries.
+      # @return [Integer] actual number of entries by which the read pointer
+      #   moved. If this number is less than the requested amount, the read
+      #   pointer has reached the end of the journal.
+      def move_next_skip(amount)
+        rc = Native.sd_journal_next_skip(@ptr, amount)
+        raise JournalError.new(rc) if rc < 0
+        rc
+      end
+
+      # Move the read pointer to the previous entry in the journal.
+      # @return [Boolean] True if moving to the previous entry was successful.
+      # @return [Boolean] False if unable to move to the previous entry,
+      #   indicating that the pointer has reached the beginning of the journal.
+      def move_previous
+        rc = Native.sd_journal_previous(@ptr)
+        raise JournalError.new(rc) if rc < 0
+        rc > 0
+      end
+
+      # Move the read pointer backwards by `amount` entries.
+      # @return [Integer] actual number of entries by which the read pointer
+      #   was moved.  If this number is less than the requested amount, the
+      #   read pointer has reached the beginning of the journal.
+      def move_previous_skip(amount)
+        rc = Native.sd_journal_previous_skip(@ptr, amount)
+        raise JournalError.new(rc) if rc < 0
+        rc
+      end
+
+      # Seek to a position in the journal.
+      # Note: after seeking, you must call {#move_next} or {#move_previous}
+      #   before you can call {#read_field} or {#current_entry}.
+      #
+      # @param [Symbol, Time] whence one of :head, :tail, or a Time instance.
+      #   `:head` (or `:start`) will seek to the beginning of the journal.
+      #   `:tail` (or `:end`) will seek to the end of the journal. When a
+      #   `Time` is provided, seek to the journal entry logged closest to that
+      #   time. When a String is provided, assume it is a cursor from {#cursor}
+      #   and seek to that entry.
+      # @return [True]
+      def seek(where)
+        rc = case
+             when [:head, :start].include?(where)
+               Native.sd_journal_seek_head(@ptr)
+             when [:tail, :end].include?(where)
+               Native.sd_journal_seek_tail(@ptr)
+             when where.is_a?(Time)
+               Native.sd_journal_seek_realtime_usec(
+                @ptr,
+                where.to_i * 1_000_000
+               )
+             when where.is_a?(String)
+               Native.sd_journal_seek_cursor(@ptr, where)
+             else
+               raise ArgumentError.new("Unknown seek type: #{where.class}")
+             end
+
+        raise JournalErrornew(rc) if rc < 0
+
+        true
+      end
+    end
+  end
+end

data/lib/systemd/journal/version.rb

@@ -1,6 +1,6 @@
 module Systemd
   class Journal
     # The version of the systemd-journal gem.
-    VERSION = '1.0.2'
+    VERSION = '1.1.0'
   end
 end

data/lib/systemd/journal/waitable.rb

@@ -0,0 +1,74 @@
+module Systemd
+  class Journal
+    module Waitable
+      # Block until the journal is changed.
+      # @param timeout_usec [Integer] maximum number of microseconds to wait
+      #   or `-1` to wait indefinitely.
+      # @example Wait for an event for a maximum of 3 seconds
+      #   j = Systemd::Journal.new
+      #   j.seek(:tail)
+      #   if j.wait(3 * 1_000_000)
+      #     # event occurred
+      #   end
+      # @return [Nil] the wait time was reached (no events occured).
+      # @return [Symbol] :append new entries were appened to the journal.
+      # @return [Symbol] :invalidate journal files were added/removed/rotated.
+      def wait(timeout_usec = -1, opts = {})
+        if opts[:select]
+          wait_select(timeout_usec)
+        else
+          rc = Native.sd_journal_wait(@ptr, timeout_usec)
+          raise JournalError.new(rc) if rc.is_a?(Fixnum) && rc < 0
+          rc == :nop ? nil : rc
+        end
+      end
+
+      # Determine if calls to {#wait} with `select: true` will reliably wake
+      # when a change occurs. If false, there might be some (unknown) latency
+      # involved between when an change occurs and when {#wait} returns.
+      # @return [Boolean]
+      def wait_select_reliable?
+        Native.sd_journal_reliable_fd(@ptr) > 0
+      end
+
+      # Block and wait for new entries to be appended to the journal. When new
+      # entries are written, yields them in turn.  Note that this function does
+      # not automatically seek to the end of the journal prior to waiting.
+      # This method Does not return.
+      # @example Print out events as they happen
+      #   j = Systemd::Journal.new
+      #   j.seek(:tail)
+      #   j.watch do |event|
+      #     puts event.message
+      #   end
+      def watch
+        loop { (yield current_entry while move_next) if wait }
+      end
+
+      private
+
+      def wait_select(timeout_usec)
+        timeout_sec = (timeout_usec == -1 ? nil : timeout_usec / 1e6)
+        r, *_ = IO.select([io_object], [], [], timeout_sec)
+        r ? reason_for_wakeup : nil
+      end
+
+      def io_object
+        @io ||= IO.new(file_descriptor, autoclose: false)
+      end
+
+      def file_descriptor
+        fd = Native.sd_journal_get_fd(@ptr)
+        raise JournalError.new(rc) if fd < 0
+        fd
+      end
+
+      def reason_for_wakeup
+        rc = Native.sd_journal_process(@ptr)
+        raise JournalError.new(rc) if rc.is_a?(Fixnum) && rc < 0
+        rc == :nop ? nil : rc
+      end
+
+    end
+  end
+end

data/lib/systemd/journal/{compat.rb → writable.rb}

@@ -3,9 +3,10 @@ require 'systemd/journal_error'
 
 module Systemd
   class Journal
-    # This module provides compatibility with the systemd-journal.gem
-    # by Daniel Mack (https://github.com/zonque/systemd-journal.gem)
-    module Compat
+    # This module provides write access to the systemd Journal, compatible with
+    # the systemd-journal.gem by Daniel Mack
+    # (https://github.com/zonque/systemd-journal.gem).
+    module Writable
        # system is unusable
       LOG_EMERG   = 0
       # action must be taken immediately

data/lib/systemd/journal_entry.rb

@@ -14,10 +14,14 @@ module Systemd
       @entry  = entry
       @fields = entry.map do |key, value|
         name = key.downcase.to_sym
-        define_singleton_method(name){ value } unless respond_to?(name)
+        define_singleton_method(name) { value } unless respond_to?(name)
         name
       end
+    end
 
+    # not all journal entries will have all fields.  don't raise an error.
+    def method_missing(m)
+      nil
     end
 
     # Get the value of a given field in the entry, or nil if it doesn't exist
@@ -27,7 +31,28 @@ module Systemd
 
     def each
       return to_enum(:each) unless block_given?
-      @entry.each{ |key, value| yield [key, value] }
+      @entry.each { |key, value| yield [key, value] }
+    end
+
+    def catalog(opts = {})
+      return nil unless catalog?
+
+      opts[:replace] = true unless opts.key?(:replace)
+
+      cat = Systemd::Journal.catalog_for(self[:message_id])
+      # catalog_for does not do field substitution for us, so we do it here
+      # if requested
+      opts[:replace] ? field_substitute(cat) : cat
+    end
+
+    def catalog?
+      !self[:message_id].nil?
+    end
+
+    private
+
+    def field_substitute(msg)
+      msg.gsub(/@[A-Z_0-9]+@/) { |field| self[field[1..-2]] || field }
     end
   end
 end

data/spec/no_ffi.rb

@@ -1,4 +1,4 @@
 $NO_FFI_SPEC = true
 module Systemd::Journal::Native ; end
 
-puts "Warning: running specs without libsystemd-journal and libsystemd-id128"
+puts 'Warning: running specs without libsystemd-journal and libsystemd-id128'

data/spec/spec_helper.rb

@@ -8,7 +8,7 @@ RSpec.configure do |config|
   config.before(:each) do
 
     # Stub open and close calls
-    dummy_open = ->(ptr, flags, path=nil) do
+    dummy_open = ->(ptr, flags, path = nil) do
       ptr.write_pointer(nil)
       0
     end
@@ -19,7 +19,7 @@ RSpec.configure do |config|
 
     # Raise an exception if any native calls are actually called
     native_calls = Systemd::Journal::Native.methods.select do |m|
-      m.to_s.start_with?("sd_")
+      m.to_s.start_with?('sd_')
     end
 
     native_calls -= [

data/spec/systemd/id128_spec.rb

@@ -9,7 +9,7 @@ describe Systemd::Id128 do
         out.write_array_of_uint8(dummy)
         0
       end
-      Systemd::Id128.boot_id.should eq("a10c" * 8)
+      expect(Systemd::Id128.boot_id).to eq('a10c' * 8)
     end
   end
 
@@ -20,7 +20,7 @@ describe Systemd::Id128 do
         out.write_array_of_uint8(dummy)
         0
       end
-      Systemd::Id128.machine_id.should eq("a10c" * 8)
+      expect(Systemd::Id128.machine_id).to eq('a10c' * 8)
     end
   end
 
@@ -31,9 +31,9 @@ describe Systemd::Id128 do
         out.write_array_of_uint8(dummy)
         0
       end
-      Systemd::Id128.random.should eq("a10c" * 8)
-    end    
+      expect(Systemd::Id128.random).to eq('a10c' * 8)
+    end
 
   end
-  
+
 end

data/spec/systemd/journal_entry_spec.rb

@@ -3,41 +3,95 @@ require 'spec_helper'
 describe Systemd::JournalEntry do
   subject do
     Systemd::JournalEntry.new(
-      '_PID'     => '125',
-      '_EXE'     => '/usr/bin/sshd',
-      'PRIORITY' => '4',
-      'OBJECT_ID'=> ':)'
+      '_PID'      => '125',
+      '_EXE'      => '/usr/bin/sshd',
+      'PRIORITY'  => '4',
+      'OBJECT_ID' => ':)'
     )
   end
 
   it 'allows enumerating entries' do
-    expect{ |b| subject.each(&b) }.to yield_successive_args(
-      ['_PID', '125'],
-      ['_EXE', '/usr/bin/sshd'],
-      ['PRIORITY', '4'],
-      ['OBJECT_ID', ':)']
+    expect { |b| subject.each(&b) }.to yield_successive_args(
+      %w{_PID 125},
+      %w{_EXE /usr/bin/sshd},
+      %w{PRIORITY 4},
+      %w{OBJECT_ID :)}
     )
   end
 
   it 'responds to field names as methods' do
-    subject._pid.should     eq('125')
-    subject.priority.should eq('4')
+    expect(subject._pid).to     eq('125')
+    expect(subject.priority).to eq('4')
   end
 
   it 'doesnt overwrite existing methods' do
-    subject.object_id.should_not eq(':)')
+    expect(subject.object_id).to_not eq(':)')
   end
 
   it 'allows accessing via [string]' do
-    subject['OBJECT_ID'].should eq(':)')
+    expect(subject['OBJECT_ID']).to eq(':)')
   end
 
   it 'allows accessing via [symbol]' do
-    subject[:object_id].should eq(':)')
+    expect(subject[:object_id]).to eq(':)')
   end
 
   it 'lists all fields it contains' do
-    subject.fields.should eq([:_pid, :_exe, :priority, :object_id])
+    expect(subject.fields).to eq([:_pid, :_exe, :priority, :object_id])
+  end
+
+  it 'should not have a catalog' do
+    expect(subject.catalog?).to be_false
+  end
+
+  it "doesn't throw NoMethod errors" do
+    expect { subject.froobaz }.not_to raise_error
+  end
+
+  context 'with catalogs' do
+    subject do
+      Systemd::JournalEntry.new(
+        '_PID'       => '125',
+        '_EXE'       => '/usr/bin/sshd',
+        'PRIORITY'   => '4',
+        'MESSAGE_ID' => 'ab1fced28a0'
+      )
+    end
+
+    describe '#catalog?' do
+      it 'returns true if the entry has a message ID' do
+        expect(subject.catalog?).to be_true
+      end
+    end
+
+    describe '#catalog' do
+      it 'asks the journal for the message with our ID' do
+        Systemd::Journal
+          .should_receive(:catalog_for)
+          .with('ab1fced28a0')
+          .and_return('catalog')
+
+        expect(subject.catalog).to eq('catalog')
+      end
+
+      it 'does field replacement by default' do
+        Systemd::Journal
+          .should_receive(:catalog_for)
+          .with('ab1fced28a0')
+          .and_return('catalog @_PID@ @PRIORITY@')
+
+        expect(subject.catalog).to eq('catalog 125 4')
+      end
+
+      it 'skips field replacement if requested' do
+        Systemd::Journal
+          .should_receive(:catalog_for)
+          .with('ab1fced28a0')
+          .and_return('cat @_PID@ @PRIORITY@')
+
+        expect(subject.catalog(replace: false)).to eq('cat @_PID@ @PRIORITY@')
+      end
+    end
   end
 
 end