cloudinit_userdata 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2d7e996e9f77331d34d824d38ac387360d4bd5ec
-  data.tar.gz: 2facecfe592044513a243ab9e0624fb0d685f433
+  metadata.gz: 6bdf94b32e15500f0207061b0e75d47a43218def
+  data.tar.gz: 167dd5eaeacba560bb01c830f9d9bfb1af9b9fba
 SHA512:
-  metadata.gz: 3b7b9d40680f06be3b4ac052915d06828e678ce1d544f9e893c88c49e9d7e37a50872678945c5e723cab4cef692f0eae730df8483a9674fe279a13b59803a23f
-  data.tar.gz: d707e9a42c52197fbda588714a597b3c83d5d1a0cba5be0c10c792a1c034b1f637fe4f859071c5d2ee6506f53c31fdfcd803c7b183f96a9b959120620f8d9ba1
+  metadata.gz: 5392c767a737ad08b23bc52907436b33de40436eb4875932b146c672821b9ea4f8fe6b83227b47047aeb3e0ec6dcd9d091aea9ccf72702166609a81c2ce8df87
+  data.tar.gz: 62d5381c1e5fbd4485fdca9dbc1f5f9bc67475e4cd7730fad727dcc49864a423b17acc5b9ba079a07fe1f01d76ae08a1aabf73be1e47a242f7baffd2fc3cc831

data/README.md

@@ -11,25 +11,52 @@ Usage
 ```ruby
 require 'cloudinit_userdata'
 
-userdata = CloudInit::Userdata.new <<-USERDATA.strip
+userdata = CloudInit::Userdata.parse <<-USERDATA.strip
   #!/bin/bash
 
   echo "Hello world!"
 USERDATA
 
-userdata.script? # true
-userdata.cloud_config? # false
-userdata.json? # false
+userdata.class # CloudInit::Userdata::ShellScript
 userdata.valid? # true
 ```
 
-Understand userdata scripts (begin with `#!`), JSON (used by CoreOS/ignition),
-and all of the [core CloudInit formats](http://cloudinit.readthedocs.org/en/latest/topics/format.html).
+Currently understands all of the
+[core CloudInit formats](http://cloudinit.readthedocs.org/en/latest/topics/format.html).
+Mime Multipart and gzipped userdata are also supported.
+
+An adapter is also included for JSON userdata (used by CoreOS/ignition), but it
+is not loaded by default, since it is not part of the original implementation.
+To include it, do the following somewhere:
+
+```
+require 'cloudinit_userdata/formats/json'
+CloudInit::Userdata.register_format(CloudInit::Userdata::JSON)
+```
+
+Custom Adapters
+---------------
+
+You can implement formatters for your custom types of userdata. Formatters
+should inherit from `CloudInit::Userdata`, and are expected to implement the
+`.match?` method at minimum.
+
+Formatters may also implement `#validate`, which will be called automatically
+by `CloudInit::Userdata#valid?`.
+
+Formatters may also implement `.mimetypes` and return an array of mimetype
+strings that will be recognized for Mime Multipart userdata.
+
+Finally, custom formatters must be registered with this library using the
+`CloudInit::Userdata.register_format(<your format class>)`.
 
 Known Limitations
 -----------------
 
-* Currently, this library does not support [mime-multi part files](http://cloudinit.readthedocs.org/en/latest/topics/format.html#mime-multi-part-archive). We plan to eventually support this feature, but it is currently low priority.
+* This library does not validate the semantics of userdata, since the only way
+  to do that accurately is to actually run the userdata on a machine, and we
+  obviously can't do that. Rather, this library attempts to provide some basic
+  intelligence and parse-checking around userdata formats.
 
 Contributing
 ------------

data/cloudinit_userdata.gemspec

@@ -18,6 +18,8 @@ Gem::Specification.new do |spec|
   spec.bindir        = 'bin'
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
 
+  spec.add_dependency 'mail', '~> 2.6'
+
   spec.add_development_dependency 'rake', '~> 0'
   spec.add_development_dependency 'rspec', '~> 3'
   spec.add_development_dependency 'rdoc', '~> 4'

data/lib/cloudinit_userdata/errors.rb

@@ -1,6 +1,8 @@
 module CloudInit
-  class Error < RuntimeError; end
-  class InvalidUserdata < Error; end
-  class InvalidUserdataType < InvalidUserdata; end
-  class ParseError < InvalidUserdata; end
+  class Userdata
+    class Error < RuntimeError; end
+    class InvalidUserdata < Error; end
+    class InvalidFormat < InvalidUserdata; end
+    class ParseError < InvalidUserdata; end
+  end
 end

data/lib/cloudinit_userdata/formats/blank.rb

@@ -0,0 +1,15 @@
+module CloudInit
+  class Userdata
+    class Blank < Userdata
+      REGEXP = /\A[[:space:]]*\z/
+
+      def self.match?(value)
+        value.nil? || !REGEXP.match(value).nil?
+      end
+
+      def empty?
+        true
+      end
+    end
+  end
+end

data/lib/cloudinit_userdata/formats/cloud_boothook.rb

@@ -0,0 +1,16 @@
+module CloudInit
+  class Userdata
+    class CloudBoothook < Userdata
+      PREFIX = '#cloud-boothook'.freeze
+      MIMETYPES = %w(text/cloud-boothook).freeze
+
+      def self.match?(value)
+        value.start_with?(PREFIX)
+      end
+
+      def self.mimetypes
+        MIMETYPES
+      end
+    end
+  end
+end

data/lib/cloudinit_userdata/formats/cloud_config.rb

@@ -0,0 +1,25 @@
+require 'yaml'
+require 'cloudinit_userdata/errors'
+
+module CloudInit
+  class Userdata
+    class CloudConfig < Userdata
+      PREFIX = "#cloud-config\n".freeze
+      MIMETYPES = %w(text/cloud-config).freeze
+
+      def validate
+        YAML.safe_load(raw)
+      rescue Psych::SyntaxError => e
+        raise ParseError, "Contains invalid YAML at line #{e.line}, column #{e.column}: #{e.problem} #{e.context}"
+      end
+
+      def self.match?(value)
+        value.start_with?(PREFIX)
+      end
+
+      def self.mimetypes
+        MIMETYPES
+      end
+    end
+  end
+end

data/lib/cloudinit_userdata/formats/gzipped.rb

@@ -0,0 +1,44 @@
+require 'zlib'
+require 'stringio'
+
+module CloudInit
+  class Userdata
+    # This class is really just a special formatter that wraps another
+    # formatter and delegates an un-gzipped version of the string to the
+    # underlying parser.
+    class Gzipped < Userdata
+      PREFIX = "\x1F\x8B".b.freeze
+
+      attr_accessor :formatter
+
+      def initialize(raw)
+        super
+        self.formatter = CloudInit::Userdata.parse(self.raw)
+      end
+
+      def raw(decompressed = true)
+        if decompressed
+          Zlib::GzipReader.new(StringIO.new(super())).read
+        else
+          super()
+        end
+      end
+
+      def empty?
+        formatter.empty?
+      end
+
+      def validate
+        formatter.validate
+      end
+
+      def to_s
+        raw(false)
+      end
+
+      def self.match?(value)
+        !value.nil? && value[0..1] == PREFIX
+      end
+    end
+  end
+end

data/lib/cloudinit_userdata/formats/include.rb

@@ -0,0 +1,16 @@
+module CloudInit
+  class Userdata
+    class Include < Userdata
+      PREFIX = '#include'.freeze
+      MIMETYPES = %w(text/x-include-url text/x-include-once-url).freeze
+
+      def self.match?(value)
+        value.start_with?(PREFIX)
+      end
+
+      def self.mimetypes
+        MIMETYPES
+      end
+    end
+  end
+end

data/lib/cloudinit_userdata/formats/json.rb

@@ -0,0 +1,25 @@
+require 'json'
+require 'cloudinit_userdata/errors'
+
+module CloudInit
+  class Userdata
+    class JSON < Userdata
+      PREFIXES = %w([ {).freeze
+      MIMETYPES = %w(application/json).freeze
+
+      def validate
+        JSON.parse(raw)
+      rescue JSON::ParserError => e
+        raise ParseError, "Contains invalid JSON: #{e.message.sub(/^(\d+): /, '')}"
+      end
+
+      def self.match?(value)
+        PREFIXES.any? { |prefix| value.start_with?(prefix) }
+      end
+
+      def self.mimetypes
+        MIMETYPES
+      end
+    end
+  end
+end

data/lib/cloudinit_userdata/formats/mime_multipart.rb

@@ -0,0 +1,43 @@
+require 'mail'
+require 'cloudinit_userdata/errors'
+
+module CloudInit
+  class Userdata
+    class MimeMultipart < Userdata
+      MATCH_STRING = 'Content-Type: multipart/mixed'.freeze
+      MIMETYPES = %w(multipart/mixed).freeze
+
+      attr_accessor :formatters
+
+      def initialize(raw)
+        super
+        self.formatters = self.class.parse_formatters(raw)
+      end
+
+      def validate
+        formatters.each(&:validate)
+      end
+
+      def empty?
+        formatters.all?(&:empty?)
+      end
+
+      def self.match?(value)
+        value.include?(MATCH_STRING)
+      end
+
+      def self.mimetypes
+        MIMETYPES
+      end
+
+      def self.parse_formatters(raw)
+        Mail.new(raw).parts.map do |part|
+          mime = part.mime_type
+          formatter = Userdata.formats.find { |f| f.mimetypes.include?(mime) }
+          raise InvalidFormat, "Userdata format for mime type #{mime} not found" unless formatter
+          formatter.new(part.body.raw_source)
+        end
+      end
+    end
+  end
+end

data/lib/cloudinit_userdata/formats/part_handler.rb

@@ -0,0 +1,16 @@
+module CloudInit
+  class Userdata
+    class PartHandler < Userdata
+      PREFIX = '#part-handler'.freeze
+      MIMETYPES = %w(text/part-handler).freeze
+
+      def self.match?(value)
+        value.start_with?(PREFIX)
+      end
+
+      def self.mimetypes
+        MIMETYPES
+      end
+    end
+  end
+end

data/lib/cloudinit_userdata/formats/shell_script.rb

@@ -0,0 +1,24 @@
+require 'cloudinit_userdata/errors'
+
+module CloudInit
+  class Userdata
+    class ShellScript < Userdata
+      SHEBANG = '#!'.freeze
+      SHEBANG_REGEXP = /^#!\S.+\n/
+      MIMETYPES = %w(text/x-shellscript).freeze
+
+      def validate
+        return if raw =~ SHEBANG_REGEXP
+        raise InvalidUserdata, 'Script is not a properly formatted to call an executable on line 1'
+      end
+
+      def self.match?(value)
+        value.start_with?(SHEBANG)
+      end
+
+      def self.mimetypes
+        MIMETYPES
+      end
+    end
+  end
+end

data/lib/cloudinit_userdata/formats/upstart_job.rb

@@ -0,0 +1,16 @@
+module CloudInit
+  class Userdata
+    class UpstartJob < Userdata
+      PREFIX = '#upstart-job'.freeze
+      MIMETYPES = %w(text/upstart-job).freeze
+
+      def self.match?(value)
+        value.start_with?(PREFIX)
+      end
+
+      def self.mimetypes
+        MIMETYPES
+      end
+    end
+  end
+end

data/lib/cloudinit_userdata/userdata.rb

@@ -1,48 +1,22 @@
-require 'zlib'
-require 'stringio'
-require 'cloudinit_userdata/validator'
+require 'cloudinit_userdata/errors'
 
 module CloudInit
   class Userdata
-    BLANK_REGEXP = /\A[[:space:]]*\z/
-    GZIP_PREFIX = "\x1F\x8B".b.freeze
-
-    SHEBANG = '#!'.freeze
-    CLOUD_CONFIG_PREFIX = "#cloud-config\n".freeze
-    JSON_PREFIXES = %w([ {).freeze
-    PREFIXES = JSON_PREFIXES + [
-      SHEBANG, CLOUD_CONFIG_PREFIX,
-      '#include', '#upstart-job', '#cloud-boothook', '#part-handler'
-    ].freeze
+    @formats = []
 
     attr_accessor :raw
+    alias to_s raw
 
     def initialize(raw)
       self.raw = raw
     end
 
-    def script?
-      to_s(:human).start_with?(SHEBANG)
-    end
-
-    def cloud_config?
-      to_s(:human).start_with?(CLOUD_CONFIG_PREFIX)
-    end
-
-    def json?
-      JSON_PREFIXES.include?(to_s(:human)[0])
-    end
-
     def empty?
-      raw.nil? || !BLANK_REGEXP.match(to_s(:human)).nil?
-    end
-
-    def gzipped?
-      !raw.nil? && raw[0..1] == GZIP_PREFIX
+      false
     end
 
-    def decompressed
-      Zlib::GzipReader.new(StringIO.new(raw)).read
+    def validate
+      # noop
     end
 
     def valid?
@@ -52,16 +26,26 @@ module CloudInit
       false
     end
 
-    def validate
-      Validator.new(self).call
+    def self.match?(_value)
+      raise NotImplementedError
+    end
+
+    def self.mimetypes
+      []
+    end
+
+    def self.parse(value)
+      formatter = @formats.find { |f| f.match?(value) }
+      raise InvalidFormat, 'Unrecognized userdata format' unless formatter
+      formatter.new(value)
+    end
+
+    def self.register_format(klass)
+      @formats << klass unless @formats.include?(klass)
     end
 
-    def to_s(format = nil)
-      case format
-      when nil, :raw then raw
-      when :human, :decompressed
-        gzipped? ? decompressed : raw
-      end
+    class << self
+      attr_reader :formats
     end
   end
 end

data/lib/cloudinit_userdata/version.rb

@@ -1,5 +1,5 @@
 module CloudInit
   class Userdata
-    VERSION = '0.0.1'.freeze
+    VERSION = '1.0.0'.freeze
   end
 end

data/lib/cloudinit_userdata.rb

@@ -3,7 +3,39 @@ $LOAD_PATH.unshift File.dirname(__FILE__)
 require 'cloudinit_userdata/version'
 require 'cloudinit_userdata/errors'
 require 'cloudinit_userdata/userdata'
-require 'cloudinit_userdata/validator'
 
 module CloudInit
 end
+
+#
+# Register our userdata formats.
+#
+
+# Note that the Gzipped formatter should go first so that it can deal with
+# binary data.
+require 'cloudinit_userdata/formats/gzipped'
+CloudInit::Userdata.register_format(CloudInit::Userdata::Gzipped)
+
+require 'cloudinit_userdata/formats/blank'
+CloudInit::Userdata.register_format(CloudInit::Userdata::Blank)
+
+require 'cloudinit_userdata/formats/cloud_boothook'
+CloudInit::Userdata.register_format(CloudInit::Userdata::CloudBoothook)
+
+require 'cloudinit_userdata/formats/cloud_config'
+CloudInit::Userdata.register_format(CloudInit::Userdata::CloudConfig)
+
+require 'cloudinit_userdata/formats/include'
+CloudInit::Userdata.register_format(CloudInit::Userdata::Include)
+
+require 'cloudinit_userdata/formats/mime_multipart'
+CloudInit::Userdata.register_format(CloudInit::Userdata::MimeMultipart)
+
+require 'cloudinit_userdata/formats/part_handler'
+CloudInit::Userdata.register_format(CloudInit::Userdata::PartHandler)
+
+require 'cloudinit_userdata/formats/shell_script'
+CloudInit::Userdata.register_format(CloudInit::Userdata::ShellScript)
+
+require 'cloudinit_userdata/formats/upstart_job'
+CloudInit::Userdata.register_format(CloudInit::Userdata::UpstartJob)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cloudinit_userdata
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Jake Bell
@@ -10,6 +10,20 @@ bindir: bin
 cert_chain: []
 date: 2016-02-23 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -127,8 +141,17 @@ files:
 - cloudinit_userdata.gemspec
 - lib/cloudinit_userdata.rb
 - lib/cloudinit_userdata/errors.rb
+- lib/cloudinit_userdata/formats/blank.rb
+- lib/cloudinit_userdata/formats/cloud_boothook.rb
+- lib/cloudinit_userdata/formats/cloud_config.rb
+- lib/cloudinit_userdata/formats/gzipped.rb
+- lib/cloudinit_userdata/formats/include.rb
+- lib/cloudinit_userdata/formats/json.rb
+- lib/cloudinit_userdata/formats/mime_multipart.rb
+- lib/cloudinit_userdata/formats/part_handler.rb
+- lib/cloudinit_userdata/formats/shell_script.rb
+- lib/cloudinit_userdata/formats/upstart_job.rb
 - lib/cloudinit_userdata/userdata.rb
-- lib/cloudinit_userdata/validator.rb
 - lib/cloudinit_userdata/version.rb
 homepage: https://www.packet.net
 licenses: []

data/lib/cloudinit_userdata/validator.rb

@@ -1,49 +0,0 @@
-require 'cloudinit_userdata/errors'
-
-module CloudInit
-  class Userdata
-    class Validator
-      attr_accessor :userdata
-
-      def initialize(userdata)
-        self.userdata = userdata
-      end
-
-      def call
-        case
-        when userdata.empty? then return
-        when ::CloudInit::Userdata::PREFIXES.none? { |prefix| value.start_with?(prefix) }
-          raise InvalidUserdataType, 'Unrecognized userdata format'
-        when userdata.script? then validate_script
-        when userdata.cloud_config? then validate_cloud_config
-        when userdata.json? then validate_json
-        end
-      end
-
-      private
-
-      def validate_script
-        return if value =~ /^#!\S.+\n/
-        raise InvalidUserdata, 'Script is not a properly formatted to call an executable on line 1'
-      end
-
-      def validate_cloud_config
-        require 'yaml'
-        YAML.safe_load(value)
-      rescue Psych::SyntaxError => e
-        raise ParseError, "Contains invalid YAML at line #{e.line}, column #{e.column}: #{e.problem} #{e.context}"
-      end
-
-      def validate_json
-        require 'json'
-        JSON.parse(value)
-      rescue JSON::ParserError => e
-        raise ParseError, "Contains invalid JSON: #{e.message.sub(/^(\d+): /, '')}"
-      end
-
-      def value
-        @value ||= userdata.to_s(:human)
-      end
-    end
-  end
-end