stashboard-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e28d6db972c33a1f1693f13a3bc910c1306261e5
+  data.tar.gz: 687361e79130eeafd1b60c88cc5b563be84d56a7
+SHA512:
+  metadata.gz: c3240f9555c430b4b8c1041efd6b0a966f62113dc0d2485789fb1ac85a9b64357741a7a6bc73b4bb68292d2c47bcf1d3722371f8d754707379be27527328b36d
+  data.tar.gz: da535101c27dc2f27a05d100ce7ec037f9f271a709523674c2899406ae5f770a000997b2602d7db017d800e129b7f120111063267fd48d490609f4ceac4899c7

data/.gitignore

@@ -0,0 +1,5 @@
+pkg/*
+*.gem
+.bundle
+doc/*
+.yardoc

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in stashboard.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,22 @@
+PATH
+  remote: .
+  specs:
+    stashboard (0.0.1)
+      oauth (>= 0.4.4)
+      yajl-ruby (>= 0.8.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    oauth (0.4.4)
+    yajl-ruby (0.8.1)
+    yard (0.6.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  oauth (>= 0.4.4)
+  stashboard!
+  yajl-ruby (>= 0.8.1)
+  yard (>= 0.6.4)

data/README.md

@@ -0,0 +1,158 @@
+# Updated Stashboard gem
+
+Simple little ruby library for interacting with a Stashboard instance
+([http://www.stashboard.org](http://www.stashboard.org).
+
+Stashboard is a Python application designed to be run on the Google App Engine,
+which provides a system status type page for your application similar to the
+status pages offered by [Amazon AWS](http://status.aws.amazon.com/), or 
+[Google Apps](http://www.google.com/appsstatus).
+
+This library doesn't address setting up your Stashboard instance, but
+simplifies interacting with it from Ruby.
+
+This is an updated version of the stashboard gem from [Sam Mulbe](https://github.com/smulube/stashboard-ruby), with fixes from [Brian Stolz](https://github.com/tecnobrat/stashboard-ruby). This new gem has been created to implement some much-needed updates, as the previous gem is no longer being actively maintained.
+
+I've tried to add some extra set-up instructions to the below usage to help beginners aswell.
+
+# Setup
+    
+### 1. Download the SDK
+Download the latest [Python SDK for Google App Engine](http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Python).
+
+### 2. Get the project
+Download and extract the [Stashboard project](http://github.com/twilio/stashboard/tarball/master) to your computer.
+
+### 3. Run Locally
+Open the SDK, choose
+```
+File > Add Existing Application...
+```
+
+Navigate to:
+```
+Propject folder > stashboard
+```
+Select open, press Run and navigate to *http://localhost:{port}* to see your Stashboard installation.
+
+### 4. Deploy to AppSpot
+4.1. [Sign up for an AppSpot account](https://developers.google.com/appengine/docs/python/gettingstartedpython27/uploading?csw=1).
+
+4.2. Create an application within AppSpot - specifying Python as the language.
+
+4.3. Update your *app.yaml* file (within the local project folder) and change the *application-id* to the name of your newly created application.
+
+4.4. Hit the 'Deploy' button, wait a couple of seconds, and then navigate to *http://{app-name}.appspot.com* to enjoy your new status dashboard
+
+# Usage
+Into your Gemfile add the line
+```ruby
+gem "stashboard-ruby"
+```
+
+Inside of your project, first create a new Stashboard
+```ruby
+stashboard = Stashboard::Stashboard.new("https://your-app.appspot.com", "<stashboard_oauth_token>", "<stashboard_oauth_secret>")
+```
+
+To receive an array of services:
+```ruby
+stashboard.services
+=begin
+ =>  [
+        {
+          "description"=>"Mail Service", 
+          "url"=>"https://YOURAPP.appspot.com/api/v1/services/mail-service", 
+          "list"=>{
+            "url"=>"https://YOURAPP.appspot.com/api/v1/service-lists/application-services", 
+            "description"=>"The main services that run the application", 
+            "name"=>"Application Services", 
+            "id"=>"application-services"
+          }, 
+          "current-event"=>nil, 
+          "id"=>"mail-service", 
+          "name"=>"Mail Service"
+        }, 
+        {
+          "description"=>"PDF Cleaner", 
+          "url"=>"https://YOURAPP.appspot.com/api/v1/services/pdf-cleaner", 
+          "list"=>{
+            "url"=>"https://YOURAPP.appspot.com/api/v1/service-lists/helper-services", 
+            "description"=>"The little bits that help without being part of the app itself", 
+            "name"=>"Helper Services", "id"=>"helper-services"
+          }, 
+          "current-event"=>nil, 
+          "id"=>"pdf-cleaner", 
+          "name"=>"PDF Cleaner"
+        }, 
+        {
+          "description"=>"Website service",
+          "url"=>"https://YOURAPP.appspot.com/api/v1/services/website", 
+          "current-event"=>{
+            "status"=>{
+              "description"=>"The service is up", 
+              "level"=>"NORMAL", 
+              "default"=>true, 
+              "image"=>"https://YOURAPP.appspot.com/images/icons/iconic/check_alt.png", 
+              "url"=>"https://YOURAPP.appspot.com/api/v1/statuses/up", 
+              "id"=>"up", 
+              "name"=>"Up"
+            }, 
+            "url"=>"https://YOURAPP.appspot.com/api/v1/services/website/events/ag5zfnBsYW5ocS1zdGF0c3ISCxIFRXZlbnQYgICAgN6QwQsM", 
+            "timestamp"=>"Mon, 28 Apr 2014 14:48:16 GMT", 
+            "sid"=>"ag5zfnBsYW5ocS1zdGF0c3ISCxIFRXZlbnQYgICAgN6QwQsM", 
+            "message"=>"Web server running A-OK", 
+            "informational"=>false
+          },
+          "id"=>"website", 
+          "name"=>"Website"
+        }
+      ]
+=end
+```
+
+To receive an array of service ids:
+```ruby
+stashboard.service_ids
+# =>  ["mail-service", "pdf-cleaner", "website"]
+```
+
+To get details of a service based on it's id:
+```ruby
+stashboard.service("website")
+=begin
+ =>  {
+        "description"=>"Website service",
+        "url"=>"https://YOURAPP.appspot.com/api/v1/services/website", 
+        "current-event"=>{
+          "status"=>{
+            "description"=>"The service is up", 
+            "level"=>"NORMAL", 
+            "default"=>true, 
+            "image"=>"https://YOURAPP.appspot.com/images/icons/iconic/check_alt.png", 
+            "url"=>"https://YOURAPP.appspot.com/api/v1/statuses/up", 
+            "id"=>"up", 
+            "name"=>"Up"
+          }, 
+          "url"=>"https://YOURAPP.appspot.com/api/v1/services/website/events/ag5zfnBsYW5ocS1zdGF0c3ISCxIFRXZlbnQYgICAgN6QwQsM", 
+          "timestamp"=>"Mon, 28 Apr 2014 14:48:16 GMT", 
+          "sid"=>"ag5zfnBsYW5ocS1zdGF0c3ISCxIFRXZlbnQYgICAgN6QwQsM", 
+          "message"=>"Web server running A-OK", 
+          "informational"=>false
+        },
+        "id"=>"website", 
+        "name"=>"Website"
+      }
+=end
+```
+
+To generate an event for a service:
+```ruby
+#                       Service    Status  Message
+stashboard.create_event("website", "down", "Server unavailable, attempting to restart")
+```
+
+# FAQs
+Here are some of the frequesntly asked questions about this project
+### Where do I get my oauth token and secret?
+Once you have deployed your application onto AppSpot, you will need to run the 'setup' at *http://{app-name}.appspot.com/admin* once that is done, there is an 'credentials' link that has them both there.

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rake/clean'
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+CLEAN.include("pkg")
+CLOBBER.include("doc")
+
+namespace :doc do
+  project_root = File.expand_path(File.dirname(__FILE__))
+  doc_destination = File.join(project_root, 'doc', 'rdoc')
+
+  begin
+    require 'yard'
+    require 'yard/rake/yardoc_task'
+
+    YARD::Rake::YardocTask.new(:generate) do |yt|
+      yt.files = Dir.glob(File.join(project_root, 'lib', '**', '*.rb')) + 
+        [File.join(project_root, 'README.md') ]
+      yt.options = ['--output-dir', doc_destination, '--readme', 'README.md']
+    end
+  rescue LoadError
+    desc "Generate YARD Documentation"
+    task :generate do
+      abort "Please install the YARD gem to generate rdoc."
+    end
+  end
+end

data/lib/stashboard.rb

@@ -0,0 +1,4 @@
+$:.unshift(File.expand_path(File.dirname(__FILE__)))
+
+require "stashboard/version"
+require "stashboard/stashboard"

data/lib/stashboard/stashboard.rb

@@ -0,0 +1,176 @@
+require 'rubygems'
+require 'oauth'
+require 'yajl/json_gem'
+
+module Stashboard
+  # Main class for interacting with Stashboard.
+  class Stashboard
+    
+    # Create a new Stashboard instance.
+    #
+    # @param [String] the url of your stashboard instance (this should use https)
+    # @param [String] the oauth_token generated by your Stashboard instance (this is the long one)
+    # @param [String] the oauth_secret generated by your Stashboard instance (this is the shorter one)
+    def initialize(base_url, oauth_token, oauth_secret)
+      @consumer = OAuth::Consumer.new("anonymous", "anonymous", { :site => base_url })
+      @client = OAuth::AccessToken.new(@consumer, oauth_token, oauth_secret)
+    end
+  
+    # Gets a list of all services currently managed by the Stashboard instance
+    # 
+    # @return [Hash] containing an array of service detail hashes, or an error message
+    def services
+      response = JSON.parse(@client.get("/api/v1/services").body)
+      return response["services"] || response
+    end
+
+    # Gets an array of service ids. This is just for convenience
+    #
+    # @return [Array] containing just the service ids
+    def service_ids
+      services.collect { |s| s["id"] }
+    end
+  
+    # Get the details of an individual service managed by the Stashboard instance.
+    #
+    # @param [String] the unique id of the service (generated by Stashboard)
+    # @return [Hash] hash containing the service details
+    def service(service_id)
+      response = @client.get("/api/v1/services/#{service_id}")
+      return JSON.parse(response.body)
+    end
+  
+    # Create a new service.
+    #
+    # @param [String] the name of the service
+    # @param [String] the description of the service
+    # @return [Hash] response containing the complete service details generated by Stashboard
+    def create_service(name, description)
+      response = @client.post("/admin/api/v1/services", { "name" => name, "description" => description })
+      return JSON.parse(response.body)
+    end
+  
+    # Delete a service. This will delete all alerts for this service, so be careful.
+    #
+    # @param [String] the service id to delete
+    # @return [Hash] details of the service we've just deleted
+    def delete_service(service_id)
+      response = @client.delete("/api/v1/services/#{service_id}")
+      return JSON.parse(response.body)
+    end
+  
+    # Updates details of an existing service with a new name or description.
+    # You can't change the service_id however.
+    #
+    # @param [String] the id of the service to update
+    # @param [String] the new name
+    # @param [String] the new description
+    # @return [Hash] the updated service details
+    def update_service(service_id, name, description)
+      response = @client.post("/admin/api/v1/services/#{service_id}", { "name" => name, "description" => description })
+      return JSON.parse(response.body)
+    end
+  
+    # Returns the different levels that new statuses can use.
+    # 
+    # @return [Array] an array of the level strings
+    def levels
+      response = JSON.parse(@client.get("/api/v1/levels").body)
+      return response["levels"] || response
+    end
+  
+    # Get events for the specified service.
+    #
+    # @param [String] the service id we wer interested in
+    # @param [Hash] optional hash that restricts the returned events. Only keys that do anything are "start" and "end" which can be used to constrain the time period from which events will be returned.
+    # @return [Hash] an array of event hashes describing events for the service, or an error hash
+    def events(service_id, options = {})
+      response = JSON.parse(@client.get("/api/v1/services/#{service_id}/events", options).body)
+      return response["events"] || response
+    end
+  
+    # Create an event of a service. Events are the main way we
+    # indicate problems or resolutions of issues.
+    #
+    # @param [String] the id of the service
+    # @param [String] the id of an already existing status (i.e. "up", "down", "warning")
+    # @param [String] a descriptive message
+    # @return [Hash] the event details
+    def create_event(service_id, status_id, message)
+      response = @client.post("/admin/api/v1/services/#{service_id}/events", { "status" => status_id, "message" => message })
+      return JSON.parse(response.body)
+    end
+  
+    # Get the current event for the specified service.
+    #
+    # @param [String] the id of the service
+    # @return [Hash] hash containing the current event details
+    def current_event(service_id)
+      response = @client.get("/api/v1/services/#{service_id}/events/current")
+      return JSON.parse(response.body)
+    end
+  
+    # Get details of an individual event
+    #
+    # @param [String] the id of the service
+    # @param [String] the sid of the event. This is a unique key returned in the response when an event is created
+    # @return [Hash] hash containing the current event details
+    def event(service_id, event_sid)
+      response = @client.get("/api/v1/services/#{service_id}/events/#{event_sid}")
+      return JSON.parse(response.body)
+    end
+  
+    # Delete an event.
+    #
+    # (see #event)
+    def delete_event(service_id, event_sid)
+      response = @client.delete("/admin/api/v1/services/#{service_id}/events/#{event_sid}")
+      return JSON.parse(response.body)
+    end
+  
+    # Get all statuses.
+    #
+    # @return [Array] an array of status hashes, each hash is an individual status
+    def statuses
+      response = JSON.parse(@client.get("/api/v1/statuses").body)
+      return response["statuses"] || response
+    end
+
+    # Convenience method to return just the status ids.
+    #
+    # @return [Array] an array of just the status ids
+    def status_ids
+      statuses.collect { |s| s["id"] }
+    end
+  
+    # Get the details of the individual status.
+    #
+    # @param [String] the id of the status
+    # @return [Hash] hash containing the status details
+    def status(status_id)
+      response = @client.get("/api/v1/statuses/#{status_id}")
+      return JSON.parse(response.body)
+    end
+  
+    # Create a new status. Statuses exist independently of any Service, and are
+    # required before creating any events that use this status
+    #
+    # @param [String] the name of this status
+    # @param [String] description of the status
+    # @param [String] level string. Must be one of the levels returned from #levels
+    # @param [String] name of an image to use for this status. The complete list of images can be retrieved using #status_images, and this value should just be the image name without the directory name or the file extension.
+    # @return [Hash] hash containing the created statuses details
+    def create_status(name, description, level, image)
+      response = @client.post("/admin/api/v1/statuses", { "name" => name, "description" => description, "level" => level, "image" => image })
+      return JSON.parse(response.body)
+    end
+  
+    # Return a list of all the status images that the Stashboard server knows about.
+    #
+    # @return [Array] array of image hashes
+    def status_images
+      response = JSON.parse(@client.get("/api/v1/status-images").body)
+      return response["images"] || response
+    end
+  end
+end

data/lib/stashboard/version.rb

@@ -0,0 +1,3 @@
+module Stashboard
+  VERSION = "0.1.0"
+end

data/stashboard.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "stashboard/version"
+
+Gem::Specification.new do |s|
+  s.name        = "stashboard-ruby"
+  s.version     = Stashboard::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.date        = '2014-04-29'
+  s.authors     = ["Sam Mulube", "Brian Stolz", "Matthew Rayner"]
+  s.email       = ["sam@connectedenvironments.com", "brian@tecnobrat.com", "matt@mattrayner.co.uk"]
+  s.homepage    = "http://github.com/mattrayner/stashboard-ruby"
+  s.summary     = %q{Library for interacting with the Stashboard api. Updated to allow writes with the latest release.}
+  s.description = %q{Little library written to make interacting with the stashboard api a bit easier.}
+
+  s.rubygems_version = ">= 1.3.6"
+
+  s.add_dependency('yajl-ruby', '>= 0.8.1')
+  s.add_dependency('oauth', '>= 0.4.4')
+
+  s.add_development_dependency('yard', '>= 0.6.4')
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: stashboard-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sam Mulube
+- Brian Stolz
+- Matthew Rayner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yajl-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+- !ruby/object:Gem::Dependency
+  name: oauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.4.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.4.4
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+description: Little library written to make interacting with the stashboard api a
+  bit easier.
+email:
+- sam@connectedenvironments.com
+- brian@tecnobrat.com
+- matt@mattrayner.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- lib/stashboard.rb
+- lib/stashboard/stashboard.rb
+- lib/stashboard/version.rb
+- stashboard.gemspec
+homepage: http://github.com/mattrayner/stashboard-ruby
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Library for interacting with the Stashboard api. Updated to allow writes
+  with the latest release.
+test_files: []