zabbix-api-simple 0.1.2 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8f4e84a0886f658f05bd62ffbe03f0586006a7a1aff9b97a7915c900e2edc6e
-  data.tar.gz: d0cd327492b60c398a23d4e4885fa6445e9c4ea1e6b4aff02b264d9c529a8072
+  metadata.gz: a22800f0fc86c622d9aed2347de3474493f11063afe93574722d9775d3e183a7
+  data.tar.gz: 3e2d7da66ec9eec2a62b793016af6190b3682e23151599a0e5b92bf336b0ac51
 SHA512:
-  metadata.gz: a997c5ceaa9730a349965dab37bf09435d723641ad2a8649a848e347673ff317ae90f8eaa1ceb65378b54a1e3eacf7974d2ec6565bd1edb64f458e9a30f43351
-  data.tar.gz: 7bc895f73dd85e5a2e1e9ebcd4774d1ba9b4ca911c1abf394825d267dbb27ed2690993c6afcd0fee5d02617959b1bab042403edf306c0aa3a220ee62b4bcee47
+  metadata.gz: eff8065f139dbeefff931f0939b65ef5e1205e0d8d2869e5c6fecff3582b4f4c12182ff0084bbc3a40f8d9f702d31d382eda3585fe609c6509b7c8a7de6c3487
+  data.tar.gz: 07c4520f7944ec3a6d5253af1416c78fb62419fe885cae49db5e9409ecb7ef7b208fb56e69e69abd6918d9e69d0151beae9b2105410566bf712b462d018fbb5e

data/.gitignore

@@ -1,7 +1,7 @@
 /.bundle/
 /.yardoc
 /_yardoc/
-/Gemfile.lock/
+Gemfile.lock
 /coverage/
 /doc/
 /pkg/

data/.gitlab-ci.yml

@@ -0,0 +1,12 @@
+image: alpine:latest
+
+pages:
+  stage: deploy
+  script:
+  - echo 'Nothing to do...'
+  artifacts:
+    paths:
+    - public
+    expire_in: never
+  only:
+  - master

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 0.1.4
+- Just doc changes
+# 0.1.5
+- deps fix for pry
+- add known_objects method
+- add exception trap for json parse issues w/ note about php memory
+- change zapishell.rb to start in the api context
+- add exception for apiinfo.version (refuses auth token for some reason)
+- add pretty inspection mode to zapishell.rb
+# 0.1.6
+- force faraday 1.8 - 2.0 appears to break things

data/Gemfile

@@ -8,6 +8,7 @@ gemspec
 group :development do
     gem 'irb'
     gem 'pry'
+    gem 'yard'
 end
 
 gem "rake", "~> 13.0"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 David Parker
+
+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

@@ -1,4 +1,4 @@
-# Zabbix::Api
+# Zabbix::Api [![Gem Version](https://badge.fury.io/rb/zabbix-api-simple.svg)](https://badge.fury.io/rb/zabbix-api-simple)
 
 This zabbix api implementation for Ruby strives for three things:
 
@@ -8,7 +8,11 @@ This zabbix api implementation for Ruby strives for three things:
 
 It accomplishes these goals primarily by deferring (via Faraday) to the Zabbix API itself for just about everything - it does not attempt to re-create or otherwise "fancy-up" the API.  The reasoning behind this is that the zabbix api itself is complex enough, and the Zabbix project can alter the specifics of the api at any time.  This library just provides Ruby semantics that closely follow the API specification.  The advantage to you is that you do not need to wrap your head around two APIs (the Zabbix API proper, and the API library's API)
 
-**NOTE:**  This thing is brand new, and it works for me.  I'm certain I'm far from done adding stuff to it, but as it is at this moment it's good enough for me.  While I doubt it, there may be breaking changes going forward, so just "buyer beware".  I'll remove this note once I feel it's more or less stable.
+**Detailed documentation for this library is [>>HERE<<](https://svdasein.gitlab.io/zabbix-api)**
+
+**Source repository is [>>HERE<<](https://gitlab.com/svdasein/zabbix-api)**
+
+If you need to send data into Zabbix via the "Zabbix trapper" protocol, you might also be interested in [zabbix_sender_api](https://svdasein.gitlab.io/zabbix_sender_api)
 
 ## Installation
 
@@ -32,6 +36,8 @@ Once you have an authenticated instance of the client, syntax is basically alway
 
 `clientinstance.object.verb(<param kv pairs>)`
 
+![simple translation](images/zabbix-api-simple-simplicity.png)
+
 If "object" is unknown, "Unknown zabbix object given" will be raised.
 
 If this call results in an error from the API, a RuntimeError will be raised indicating the specifics.
@@ -55,7 +61,7 @@ opts = Optimist::options do
   opt :hostname, "Host name to search for", type: :string, required: true
 end
 
-api = Zabbix::Api::Client.new(opts[:url])
+api = Zabbix::Api::Client.new(url: opts[:url])
 
 api.login(user: opts[:user],pass:opts[:pass])
 
@@ -102,12 +108,6 @@ It attempts to authenticate you to the given server, and then drops you to a pry
 
 Refer to the API documentation for your version of Zabbix for the particulars.
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. 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/[USERNAME]/zabbix-api.
+Bug reports and pull requests are welcome on GitLab at https://gitlab.com/svdasein/zabbix-api

data/Rakefile

@@ -1,4 +1,11 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+desc "Generate yard docs in public"
+task :gendocs do 
+    puts %x(yard -o public --files CHANGELOG.md,LICENSE.txt)
+      puts %x(git add public/*)
+end
+desc "Generate docs and run :build"
+task :buildall => [ :gendocs, :build ]
+task default: :buildall

data/bin/zapishell.rb

@@ -26,4 +26,4 @@ end
 require "rubygems"
 require "bundler/setup"
 
-load Gem.bin_path("zabbix-api", "zapishell.rb")
+load Gem.bin_path("zabbix-api-simple", "zapishell.rb")

data/exe/zapishell.rb

@@ -12,12 +12,26 @@ opts = Optimist::options do
   opt :pass, "Pass to auth user with", type: :string, required: true
 end
 
+
+
+Zabbix::Api::OpenStruct.prettymode = true
+
 print "user.login: "
 api = Zabbix::Api::Client.new(url: opts[:url])
 
 ap api.login(user: opts[:user],pass:opts[:pass])
 
-binding.pry
+puts <<-END
+
+Enter api commands e.g. host.get
+
+execute known_objects for a list of known zabbix object types
+
+quit to exit - your session will be logged out for you
+
+END
+
+api.pry
 
 print "user.logout: "
 ap api.logout

data/lib/zabbix/api/client.rb

@@ -4,10 +4,15 @@ module Zabbix
     require 'faraday'
     require 'json'
     require 'set'
+    require 'amazing_print'
     require 'pry'
 
     module FaradayMiddleware
 
+      ##
+      # this middleware adapter does zabbix api essential things
+      # at the REST level, and hendles serializing/de-serializing
+      # ruby objects.
       class ZabbixApiRequest < Faraday::Middleware
 
         def initialize(app)
@@ -22,7 +27,11 @@ module Zabbix
         end
 
         def on_complete(env)
-          env[:response_body] = JSON.parse(env[:response_body])
+          begin
+            env[:response_body] = JSON.parse(env[:response_body])
+          rescue JSON::ParserError => e
+            env[:response_body] = {error: e,note: 'Check api web configuration (e.g. url, PHP memory, etc)'}
+          end
         end
 
       end
@@ -33,7 +42,42 @@ module Zabbix
 
 
 
+    ##
+    # Subclass of OpenStruct adds some niceties for REPL etc
+    #
+    class OpenStruct < OpenStruct
+
+      ##
+      # If true, inspect returns awesome_inspect instead of default
+      @@prettymode = false
 
+      class << self
+        ##
+        # returns current value of prettymode
+        #
+        def prettymode
+          @@prettymode
+        end
+        ##
+        # sets prettymod to aBool
+        #
+        def prettymode=(aBool)
+          @@prettymode = aBool
+        end
+      end
+
+      def inspect
+        if @@prettymode
+          awesome_inspect
+        else
+          super
+        end
+      end
+
+    end
+
+    ##
+    # Each instance of this class acts as a connection Zabbix's API 
     class Client
       
       class << self
@@ -43,6 +87,11 @@ module Zabbix
 
       @@apiurl = 'api_jsonrpc.php'
 
+      ##
+      # This is a list (as of zabbix 5.0) of top-level zabbix API calls
+      # that the client will understand via method_missing.  If they
+      # add new things to the api they need to be added here as well
+      # *if* you intend on using the method_missing syntax.
       @@zabbix_objects = [:action,:alert,:apiinfo,:application,:configuration,
                           :correlation,:dashboard,:dhost,:dservice,:dcheck,
                           :drule,:event,:graph,:graphitem,:graphprototype,
@@ -59,6 +108,10 @@ module Zabbix
       attr_accessor :zabobject
 
 
+      ##
+      # :url is required. You do not need to add 'api_jsonrpc.php' - this will
+      # happen automagically.  You can alter request timeout if needed by passing
+      # :timeout - the default is 60 secs
       def initialize(url: nil,timeout: 60)
         @conn = Faraday.new(
           url: url,
@@ -70,6 +123,9 @@ module Zabbix
         @zabobject = nil
       end
 
+      ##
+      # This method posts a list of params to @conn/@@apiurl.  You likely won't
+      # have need to call this directly.
       def post(args)
         args[:params] = [] if not args.has_key?(:params) or args[:params].nil?
         last = @conn.post(@@apiurl, args)
@@ -77,17 +133,66 @@ module Zabbix
         return last
       end
 
+      ##
+      # both :user and :pass are required.  This method calls user.logic 
+      # abd stores the returned auth token for future calls to the api
       def login(user: nil,pass: nil)
         res =post(method: 'user.login', params: {user: user, password:pass}, auth:nil)
         @token = res.body['result']
         OpenStruct.new(res.body)
       end
 
+      ##
+      # calls user.logout for the @token session.  You really should pay 
+      # attention to ensuring that this gets called, else you'll find over time
+      # that your sessions table is getting quite large and will start slowing
+      # down lots of stuff in zabbix.
       def logout
         OpenStruct.new(post(method: 'user.logout', params: [], auth: @token).body)
       end
 
+      ##
+      # this is the method that method_missing calls to peform the actual work.
+      # The first parameter is the top-level api call (e.g. those listed in
+      # @@zabbix_objects.  Args is a hash containing the particulars for the call.
+      # You can call this directly if you don't want to rely on method_missing.
+      #
+      # results are returned as instances of OpenStruct. If you need this to be
+      # a hash just do to_h to the returned object.
+      def call(name, *args, &block)
+        res = nil
+        if name == 'apiinfo.version'
+          res = post(method: "#{name}", params: args.first, id: '1').body
+        else
+          res = post(method: "#{name}", params: args.first, id: '1', auth: @token).body
+        end
+          raise res['error'].awesome_inspect(plain: true)  if res.has_key?('error')
+          if res.has_key?('result') and res['result'].class == Array
+            res = res['result'].collect{|each| OpenStruct.new(each)}
+          else
+            res = OpenStruct.new(res)
+          end
+          return res
+      end
+
+      ##
+      # just handy if you're doing a REPL (e.g. zapishell.rb)  Returns
+      # list of zabbix objects the api currently is aware of
+      #
+      def known_objects
+        @@zabbix_objects
+      end
 
+
+      ##
+      # this override of method_missing is the trick that lets zabbix-api-simple
+      # look quite a lot like the zabbix api documentation.  If it finds that the 
+      # method name you were trying to call is in @@zabbix_objects, then it constructs
+      # a call to that top level api entity using the parameters as arguments to the call.
+      #
+      # this is really just here as syntactical sugar - you don't *have* to use it, but
+      # if you do you'll find that you need do essentially zero mental translation between
+      # the zabbix api documentation and your code.
       def method_missing(name, *args, &block)
         if @@zabbix_objects.include?(name)
           # Clone self cuz we want to be thread safe/recursable.  This will pop off the
@@ -97,20 +202,14 @@ module Zabbix
           newcli.zabobject = name
           return newcli
         elsif @zabobject
-          object = @zabobject
-          res = post(method: "#{object}.#{name}", params: args.first, id: '1', auth: @token).body
-          raise res['error'].awesome_inspect(plain: true)  if res.has_key?('error')
-          if res.has_key?('result') and res['result'].class == Array
-            res = res['result'].collect{|each| OpenStruct.new(each)}
-          else
-            res = OpenStruct.new(res)
-          end
-          return res
+          return call("#{@zabobject}.#{name}",args.first)
         else
           raise "Unknown zabbix object given: #{name}"
         end
       end
 
+      ##
+      # returns the last response the client got from the server
       def last
         Client.last
       end

data/lib/zabbix/api/version.rb

@@ -2,6 +2,6 @@
 
 module Zabbix
   module Api
-    VERSION = "0.1.2"
+    VERSION = "0.1.6"
   end
 end

data/lib/zabbix/api.rb

@@ -3,9 +3,3 @@
 require_relative "api/version"
 require_relative "api/client"
 
-module Zabbix
-  module Api
-    class Error < StandardError; end
-    # Your code goes here...
-  end
-end