wash 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f0c229c4c749d26525382c4c26255044308b763335b4d2d6d2ea8aa3495fb9b9
+  data.tar.gz: f60ba8213ec625de9ee9961db8bccc92c85af8a30fd916056d69809446fb1987
+SHA512:
+  metadata.gz: 95ffb1adfde494f374e7dc76d02b68074ed120505e224da3667a80f9f15cc188b72fa158094a0f6dd755116a6964b396c8a65b0c67888ca4bc50603cd9f9f629
+  data.tar.gz: 6cd43ebb0dd830c14e8bf079e33dedd65fc2c25ccb6488b00073e5cf783f9b178f52992a04ae3773ed873fb5743a31774a9a2c1e642f6ae2a95190d53749ff96

data/lib/wash/entry.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+module Wash
+  # Entry represents a common base class for Wash entries. All plugin entries
+  # should extend this class.
+  class Entry
+    class << self
+      # attributes is a class-level tag specifying all the attributes that
+      # make sense for instances of this specific kind of entry. It will
+      # pass the specified attributes along to attr_accessor so that instances
+      # can set their values. For example, something like
+      #
+      # @example
+      #   class Foo
+      #     # Instances of Foo will be able to set the @mtime and @meta fields
+      #     attributes :mtime, :meta
+      #   end
+      #
+      # @param [Symbol] attr An attribute that will be set
+      # @param [Symbol] attrs More attributes that will be set
+      def attributes(attr, *attrs)
+        @attributes ||= []
+        @attributes += set_fields(attr, *attrs)
+      end
+
+      # slash_replacer is a class-level tag that specifies the slash replacer.
+      # It should only be used if there is a chance that instances of the given
+      # class can contain a "#" in their names. Otherwise, slash_replacer should
+      # be ignored.
+      #
+      # @example
+      #   class Foo
+      #     # Tell Wash to replace all "/"es with ":" in the given Foo instance's
+      #     # name
+      #     slash_replacer ":"
+      #   end
+      #
+      # @param [String] char The slash replacer
+      def slash_replacer(char)
+        @slash_replacer = char
+      end
+
+      # state is a class-level tag that specifies the minimum state required
+      # to reconstruct all instances of this specific kind of entry. Each specified
+      # state field will be passed along to attr_accessor so that instances can
+      # get/set their values.
+      #
+      # @example
+      #   class Foo
+      #     # Indicates that api_key is the minimum state required to reconstruct
+      #     # instances of Foo. The gem will serialize the api_key as part of each
+      #     # instance's state key when passing them along to Wash. If Wash invokes
+      #     # a method on a specific instance, then Wash.run will restore the api_key
+      #     # prior to invoking the method (so all methods are free to directly reference
+      #     # the @api_key field). Thus, plugin authors do not have to manage their entries'
+      #     # states; the gem will do it for them via the state tag.
+      #     state :api_key
+      #   end
+      #
+      # Note that Wash.run uses {Class#allocate} when it reconstructs the entries, so
+      # it does not call the initialize method.
+      def state(field, *fields)
+        @state ||= []
+        @state += set_fields(field, *fields)
+      end
+
+      # label is a class-level tag specifying the entry's label. It is a helper for
+      # Entry schemas.
+      #
+      # @param lbl The label.
+      def label(lbl)
+        @label = lbl
+      end
+
+      # is_singleton is a class-level tag indicating that the given Entry's a singleton.
+      # It is a helper for Entry schemas.
+      #
+      # Note that if an Entry has the is_singleton tag and its name is not filled-in
+      # when that Entry is listed, then the Entry's name will be set to the specified
+      # label. This means that plugin authors do not have to set singleton entries'
+      # names, and it also enforces the convention that singleton entries' labels should
+      # match their names.
+      #
+      # @example
+      #   class Foo
+      #     label 'foo'
+      #     # If Foo's instance does not set @name, then the gem will set @name to 'foo'
+      #     is_singleton
+      #   end
+      def is_singleton
+        @singleton = true
+      end
+
+      # meta_attribute_schema sets the meta attribute's schema to schema. It is a helper
+      # for Entry schemas.
+      #
+      # @param schema A hash containing the meta attribute's JSON schema
+      def meta_attribute_schema(schema)
+        @meta_attribute_schema = schema
+      end
+
+      # metadata_schema sets the metadata schema to schema. It is a helper for Entry schemas.
+      #
+      # @param schema A hash containing the metadata's JSON schema
+      def metadata_schema(schema)
+        @metadata_schema = schema
+      end
+
+      # parent_of indicates that this kind of Entry is the parent of the given child classes
+      # (i.e. child entries). It is a helper for Entry schemas.
+      #
+      # @example
+      #   class Foo
+      #     # This indicates that Foo#list will return instances of Bar and Baz. Note
+      #     # that both direct class constants (Bar) and strings ('Baz') are valid
+      #     # input. The latter's useful when the child class is loaded after the
+      #     # parent.
+      #     parent_of Bar, 'Baz'
+      #   end
+      #
+      # @param [Wash::Entry] child_klass A child class object.
+      # @param [Wash::Entry] child_klasses More child class objects.
+      def parent_of(child_klass, *child_klasses)
+        @child_klasses ||= []
+        @child_klasses += [child_klass] + child_klasses
+      end
+
+      # children returns this Entry's child classes. It is a helper for Entry schemas, and
+      # is useful for DRY'ing up schema code when one kind of Entry's children matches another
+      # kind of Entry's children.
+      #
+      # @example
+      #   class VolumeDir
+      #     parent_of 'VolumeDir', 'VolumeFile'
+      #   end
+      #
+      #   class Volume
+      #     parent_of *VolumeDir.children
+      #   end
+      def children
+        @child_klasses
+      end
+
+      private
+
+      def schema(visited)
+        visited[type_id] = {
+          label: @label,
+          methods: methods,
+          singleton: @singleton,
+          meta_attribute_schema: @meta_attribute_schema,
+          metadata_schema: @metadata_schema,
+        }
+        unless @child_klasses
+          return
+        end
+        visited[type_id][:children] = @child_klasses
+        @child_klasses.each do |child_klass|
+          child_klass = const_get(child_klass)
+          if visited[child_klass.send(:type_id)]
+            next
+          end
+          child_klass.send(:schema, visited)
+        end
+      end
+
+      def methods
+        wash_methods = Method.instance_variable_get(:@methods)
+        methods = []
+        self.public_instance_methods.each do |method|
+          if wash_methods[method]
+            # Only include the Wash methods. This makes the script's output easier
+            # to read when debugging.
+            methods.push(method)
+          end
+        end
+        unless Wash.send(:entry_schemas_enabled?)
+          # Don't include :schema if entry-schema support is not enabled. Otherwise,
+          # Wash will return an error since entry schemas are an "on/off" feature.
+          methods.delete(:schema)
+        end
+        methods
+      end
+
+      def type_id
+        self.name
+      end
+
+      def set_fields(field, *fields)
+        fields.unshift(field)
+        fields.each do |field|
+          attr_accessor field
+        end
+        fields
+      end
+    end
+
+    # All entries have a name. Note that the name is always
+    # included in the entry's state hash.
+    attr_accessor :name
+
+    def to_json(*)
+      unless @name && @name.size > 0
+        unless singleton
+          raise "A nameless entry is being serialized. The entry is an instance of #{type_id}"
+        end
+        @name = label
+      end
+
+      hash = {
+        type_id: type_id,
+        name: @name,
+      }
+
+      # Include the methods
+      hash[:methods] = self.class.send(:methods).map do |method|
+        if prefetched_methods.include?(method)
+          [method, self.send(method)]
+        else
+          method
+        end
+      end
+
+      # Include the remaining keys. Note that these checks are here to
+      # ensure that we don't serialize empty keys. They're meant to save
+      # some space.
+      if attributes.size > 0 && (attributes_hash = to_hash(attributes))
+        hash[:attributes] = attributes_hash
+      end
+      if cache_ttls.size > 0
+        hash[:cache_ttls] = cache_ttls
+      end
+      if slash_replacer.size > 0
+        hash[:slash_replacer] = slash_replacer
+      end
+      hash[:state] = to_hash(state).merge(klass: type_id, name: @name).to_json
+      if Wash.send(:pretty_print?)
+        JSON.pretty_generate(hash)
+      else
+        JSON.generate(hash)
+      end
+    end
+
+    # type_id returns the entry's type ID, which is its fully-qualified class
+    # name.
+    def type_id
+      self.class.send(:type_id)
+    end
+
+    # prefetch indicates that the given methods should be prefetched. This means
+    # that the gem will invoke those methods on this particular entry instance and
+    # include their results when serializing that entry. Note that the methods are
+    # invoked during serialization.
+    #
+    # @example
+    #   class Foo
+    #     def initialize(content_size)
+    #       if content_size < 10
+    #         # content_size < 10, so tell the gem to invoke Foo#list and Foo#read
+    #         # on this Foo instance during its serialization
+    #         prefetch :list, :read
+    #       end
+    #     end
+    #   end
+    #
+    # @param [Symbol] method A method that should be prefetched.
+    # @param [Symbol] methods More methods that should be prefetched.
+    def prefetch(method, *methods)
+      prefetched_methods.concat([method] + methods)
+    end
+
+    # cache_ttls sets the cache TTLs (time-to-live) of the given methods.
+    #
+    # @example
+    #   class Foo
+    #     def initialize(content_size)
+    #       if content_size > 10000
+    #         # content_size > 10000 so tell Wash to cache its read result for
+    #         # 100 seconds
+    #         cache_ttls read: 100 
+    #       end
+    #     end
+    #   end
+    #
+    # @param [Hash] ttls A hash of <method_name> => <method_ttl>
+    def cache_ttls(ttls = {})
+      @cache_ttls ||= {}
+      @cache_ttls = @cache_ttls.merge(ttls)
+    end
+
+    # schema returns the entry's schema. It should not be overridden.
+    def schema
+      schemaHash = {}
+      self.class.send(:schema, schemaHash)
+      schemaHash
+    end
+
+    private
+
+    def attributes
+      self.class.instance_variable_get(:@attributes) || []
+    end
+
+    def slash_replacer
+      self.class.instance_variable_get(:@slash_replacer) || ''
+    end
+
+    def state
+      self.class.instance_variable_get(:@state) || {}
+    end
+
+    def label
+      self.class.instance_variable_get(:@label)
+    end
+
+    def singleton
+      self.class.instance_variable_get(:@singleton)
+    end
+
+    def prefetched_methods
+      @prefetched_methods ||= []
+    end
+
+    def to_hash(fields)
+      field_hash = {}
+      fields.each do |field|
+        field = field.to_sym
+        if value = self.send(field)
+          field_hash[field] = self.send(field)
+        end
+      end
+      field_hash
+    end
+
+    def restore_state(state)
+      state.each do |field, value|
+        accessor = "#{field}=".to_sym
+        unless self.respond_to?(accessor)
+          raise "#{field} is an invalid state value"
+        end
+        self.send(accessor, value)
+      end
+    end
+  end
+end

data/lib/wash/method.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Wash
+  # @api private
+  module Method
+    def self.invoke(method, entry, *args)
+      method = method.to_sym
+      unless entry.respond_to?(method)
+        raise "Entry #{entry.name} (#{entry.type_id}) does not implement #{method}"
+      end
+      unless invocation = @methods[method]
+        raise "#{method} is not a supported Wash method"
+      end
+      invocation.call(entry, *args)
+    end
+    private_class_method :invoke
+
+    def self.method(name, &block)
+      name = name.to_sym
+      unless block
+        block = lambda do |entry, *args|
+          result = entry.send(name, *args)
+          Wash.send(:print_json, result)
+        end
+      end
+      @methods ||= {}
+      @methods[name] = block
+    end
+    private_class_method :method
+
+    method(:list)
+    method(:read)
+    method(:metadata)
+    method(:schema)
+
+    method(:exec) do |entry, *args|
+      opts, cmd, args = Wash.send(:parse_json, args[0]), args[1], args[2..-1]
+      if opts[:stdin]
+        opts[:stdin] = STDIN
+      else
+        opts[:stdin] = nil
+      end
+      ec = entry.exec(cmd, args, opts)
+      exit ec
+    end
+
+    method(:stream) do |entry, _|
+      entry.stream
+      raise "stream should never return"
+    end
+  end
+end

data/lib/wash/streamer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Wash
+  # Streamer is a class meant to be used by implementations of Wash::Entry#stream.
+  class Streamer
+    def initialize
+      @first_chunk = true
+    end
+
+    # write writes the given chunk to STDOUT then flushes it to ensure that Wash
+    # receives the data. If the chunk is the first chunk that's written, then
+    # write will print the "200" header prior to writing the chunk.
+    #
+    # @param chunk The chunk to be written
+    def write(chunk)
+        if @first_chunk
+          puts("200")
+          @first_chunk = false
+        end
+        print(chunk)
+        STDOUT.flush
+    end
+  end
+end

data/lib/wash.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Wash
+  # pretty_print enables pretty printing of methods that produce
+  # JSON output. It is a useful debugging tool.
+  def self.pretty_print
+    @pretty_print = true
+  end
+
+  # enable_entry_schemas enables {Entry schema}[https://puppetlabs.github.io/wash/docs/#entry-schemas]
+  # support. See {Wash::Entry}'s documentation for more details on
+  # the available Entry schema helpers.
+  def self.enable_entry_schemas
+    @entry_schemas_enabled = true
+  end
+
+  # prefetch_entry_schemas enables schema-prefetching. This option
+  # should be enabled once external plugin development's finished.
+  # If the external plugin is not using Entry schemas, then this
+  # option can be ignored.
+  def self.prefetch_entry_schemas
+    @prefetch_entry_schemas = true
+  end
+
+  # on_sigterm will execute the provided block when the plugin script
+  # receives a SIGTERM/SIGINT signal. It is useful for handling
+  # plugin-specific cleanup like dangling processes, files, etc.
+  #
+  # @example
+  #   class Foo
+  #     # ...
+  #     def stream
+  #       # ...
+  #       Wash.on_sigterm do
+  #         # Kill any orphaned processes/files
+  #       end
+  #       # ...
+  #     end
+  #   end
+  def self.on_sigterm(&block)
+    sigterm_handlers << block
+  end
+
+  # run is the plugin script's run function. All plugin scripts using
+  # this gem should invoke this function once they've specified the
+  # desired configuration options (e.g. like pretty_print).
+  #
+  # @param [Wash::Entry] root_klass The plugin root's class object
+  #
+  # @param [Array<String>] argv The plugin script's arguments (usually ARGV). 
+  def self.run(root_klass, argv)
+    Signal.trap('INT') do
+      handle_sigterm
+      exit 130
+    end
+    Signal.trap('TERM') do
+      handle_sigterm
+      exit 143
+    end
+
+    method, argv = next_arg(argv)
+
+    if method == "init"
+      config, argv = next_arg(argv)
+      root = root_klass.new
+      unless root.respond_to?(:init)
+        raise "Plugin root #{root.type_id} does not implement init."
+      end
+      config = parse_json(config)
+      root.init(config)
+      if @prefetch_entry_schemas
+        root.prefetch :schema
+      end
+      print_json(root)
+      return
+    end
+
+    _, argv = next_arg(argv)
+
+    state, argv = next_arg(argv)
+    state = parse_json(state)
+    klass = const_get(state.delete(:klass))
+    # Use klass#allocate instead of klass#new to give plugin authors
+    # more freedom in how they decide to setup their constructors
+    entry = klass.allocate
+    entry.send(:restore_state, state)
+
+    Method.send(:invoke, method, entry, *argv)
+  end
+
+  def self.next_arg(argv)
+    if argv.size < 1
+      raise "Invalid plugin-script invocation. See https://puppetlabs.github.io/wash/docs/external_plugins/ for details on what this should look like"
+    end
+    return argv[0], argv[1..-1]
+  end
+  private_class_method :next_arg
+
+  def self.handle_sigterm
+    sigterm_handlers.each do |handler|
+      handler.call
+    end
+  end
+  private_class_method :handle_sigterm
+
+  def self.pretty_print?
+    @pretty_print
+  end
+  private_class_method :pretty_print?
+
+  def self.entry_schemas_enabled?
+    @entry_schemas_enabled
+  end
+  private_class_method :entry_schemas_enabled?
+
+  def self.print_json(result)
+    if pretty_print?
+      result_json = JSON.pretty_generate(result)
+    else
+      result_json = JSON.generate(result)
+    end
+    puts(result_json)
+  end
+  private_class_method :print_json
+
+  def self.parse_json(json)
+    JSON.parse(json,:symbolize_names => true)
+  end
+  private_class_method :parse_json
+
+  def self.sigterm_handlers
+    @sigterm_handlers ||= []
+  end
+  private_class_method :sigterm_handlers
+
+  require 'wash/entry'
+  require 'wash/method'
+  require 'wash/streamer'
+end

metadata

@@ -0,0 +1,47 @@
+--- !ruby/object:Gem::Specification
+name: wash
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Puppet
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-07-23 00:00:00.000000000 Z
+dependencies: []
+description: A library for building Wash external plugins
+email:
+- puppet@puppet.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/wash.rb
+- lib/wash/entry.rb
+- lib/wash/method.rb
+- lib/wash/streamer.rb
+homepage: https://github.com/puppetlabs/wash-ruby
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: A library for building Wash external plugins
+test_files: []