pod4 0.9.3 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 497cdee877587568f7dbf706092902684a780149
-  data.tar.gz: baf92f8cc0c052e66bcb6afd59b51e8863fde2f7
+SHA256:
+  metadata.gz: 4166ff590c49ce621e16234388a8ef366b1530d165da50793c108827bc0f9776
+  data.tar.gz: 7462bf1368e90706f568aa4cdcc42b59226f572fa9f9b8f9b1d55f419a4c129b
 SHA512:
-  metadata.gz: ce0a49a11b357f032d2fea29f0e387f902457f9782916002fdb0b03e2de0be5e506eb75f2dd9f7ece0fdac848de2250c09b3f1fe6b8b173170be3fea851c951e
-  data.tar.gz: aa208f77f71751b999d9a0b1fbac87b8d4c77fea417162d77aa66336b33738fc720cf95904fd58fbfebdae157c0bf329873131f15b500e233ae8cab9ee4bc859
+  metadata.gz: 51653424bb26ddb8e809afd1a838ba31b4237e8f7afe1dcb12aab79521881a9415149bb910f5279ca7f27ad90af602359131108a67f57ae450a91d65ce1f3d05
+  data.tar.gz: f167459fc8541f0d989c4cf7150e8dd2adb04d522971b186fb6f058f140cb6dc81b065512159312a70a60842fc0db27ed87cbba13fa9899005fa65dd48ad688d

data/.hgtags

@@ -26,3 +26,4 @@ ccb4a8711560725e358f7fb87c76f4787eac5ed5 0.8.0
 f1b3a814e7a8c7d818b57f6d35ce7ed749573d76 0.9.1
 93b68b850a52781e2f269cb073c77aab174282e5 0.9.2
 4860714dd83ddb5b4ed0b7e32459fdaa845ac2fa 0.9.3
+77ad625b2ab048bd660194cf093015b1f2698069 0.10

data/README.md

@@ -559,3 +559,11 @@ get the idea:
 
     end
 
+Extensions
+----------
+
+There are now some mixins that you can use to extend the functionality of Pod4 models.  Have a look
+at the comments at the top of the mixin in question if you want details.
+
+* typecasting -- force columns to be a specific ruby type, validation helpers, some encoding stuff
+* encrypting  -- encrypt text columns

data/lib/pod4/encrypting.rb

@@ -0,0 +1,225 @@
+require "openssl"
+require "pod4/errors"
+require "pod4/metaxing"
+
+
+module Pod4
+
+
+  ##
+  # A mixin to give you basic encryption, transparently.
+  #
+  # Example
+  # -------
+  #
+  #     class Foo < Pod4::Model
+  #       include Pod4::Encrypting
+  #
+  #       set_key           $encryption_key
+  #       set_iv_column     :nonce
+  #       encrypted_columns :one, :two, :three
+  #
+  #       ...
+  #     end
+  #
+  # So, this adds `set_key`, `set_iv_column`, and `encrypted_columns` to the model DSL. Only
+  # `set_iv_column` is optional, and it is **highly** recommended.
+  #
+  # set_key
+  # -------
+  #
+  # Can be any string you like, but should ideally be long and random. If it's not long enough you
+  # will get an exception.  The key is used for all encryption on the model.
+  #
+  # You probably have a single key for the entire database and pass it to your application via an
+  # environment variable. But we don't care about that.
+  #
+  # set_iv_column
+  # -------------
+  #
+  # The name of a text column on the table which holds the initialisation vector, or nonce, for the
+  # record.  IVs don't have to be secret, but they should be different for each record; we take
+  # care of creating them for you.
+  #
+  # If you don't provide an IV column, then we fall back to insecure ECB mode for the encryption.
+  # Don't make us do that.
+  #
+  # encrypted_columns
+  # -----------------
+  #
+  # The list of columns to encrypt.  In addition, it acts just the same as attr_columns, so you can
+  # name the column there too, or not.  Up to you.
+  #
+  # Changes to Behaviour of Model
+  # -----------------------------
+  #
+  # `map_to_interface`: data going from the model to the interface has the relevant columns
+  # encrypted.  If the IV column is nil, we set it to a good IV.
+  #
+  # `map_to_model`: data going from the interface to the model has the relevant columns decrypted.
+  #
+  # Assumptions / limitations:
+  #
+  # * One key for all the data in the model.
+  #
+  # * a column on the table holding an initiation vector (IV, nonce) for each record. See above.
+  #
+  # * we only store encrypted data in text columns, and we can't guarantee that the encrypted data
+  #   will be the same length as when unencrypted.
+  #
+  # Additional Methods
+  # ------------------
+  #
+  # You will almost certainly never need to use these.
+  #
+  # * `encryption_iv` returns the value of the IV column of the record, whatever it is.
+  #
+  # Notes
+  # -----
+  #
+  # Encryption is provided by OpenSSL::Cipher. For more information, you should read the official
+  # Ruby docs for this; they are really helpful.
+  #
+  module Encrypting
+    CIPHER_IV    = "AES-128-CBC"
+    CIPHER_NO_IV = "AES-128-ECB"
+
+    ##
+    # A little bit of magic, for which I apologise. 
+    #
+    # When you include this module it actually adds the methods in ClassMethods to the class as if
+    # you had called `extend Encrypting:ClassMethds` *AND* adds the methods in InstanceMethods as
+    # if you had written `prepend Encrypting::InstanceMethods`.  
+    #
+    # In my defence: I didn't want to have to make you remember to do that...
+    #
+    def self.included(base)
+      base.extend  ClassMethods
+      base.send(:prepend, InstanceMethods)
+    end
+
+
+    module ClassMethods
+      include Metaxing
+
+
+      def set_key(key)
+        define_class_method(:encryption_key) {key}
+      end
+
+      def set_iv_column(column)
+        define_class_method(:encryption_iv_column) {column}
+        attr_columns column unless columns.include? column
+      end
+
+      def encrypted_columns(*ecolumns)
+        ec = encryption_columns.dup + ecolumns
+        define_class_method(:encryption_columns) {ec}
+        attr_columns( *(ec - columns) )
+      end
+
+      def encryption_key;         nil;  end
+      def encryption_iv_column;   nil;  end
+      def encryption_columns;     [];   end
+
+    end # of ClassMethods
+
+
+    module InstanceMethods
+
+      ##
+      # When mapping to the interface, encrypt the encryptable columns from the model
+      #
+      def map_to_interface
+        hash   = super.to_h
+        cipher = get_cipher(:encrypt)
+
+        # If the IV is not set we need to set it both in the model object AND the hash, since we've
+        # already obtained the hash from the model object.
+        if use_iv? && encryption_iv.nil?
+          set_encryption_iv( cipher.random_iv )
+          hash[self.class.encryption_iv_column] = encryption_iv
+        end
+
+        self.class.encryption_columns.each do |col|
+          hash[col] = crypt(cipher, encryption_iv, hash[col].to_s)
+        end
+
+        Octothorpe.new(hash)
+      end
+
+      ##
+      # When mapping to the model, decrypt the encrypted columns from the interface
+      #
+      def map_to_model(ot)
+        hash   = ot.to_h
+        cipher = get_cipher(:decrypt)
+        iv     = hash[self.class.encryption_iv_column] # not yet set on the model
+
+        self.class.encryption_columns.each do |col|
+          hash[col] = crypt(cipher, iv, hash[col])
+        end
+
+        super Octothorpe.new(hash)
+      end
+
+      ## 
+      # The value of the IV field (whatever it is) _as currently stored on the model_
+      #
+      def encryption_iv
+        return nil unless use_iv?
+        instance_variable_get( "@#{self.class.encryption_iv_column}".to_sym )
+      end
+
+      private
+
+      ##
+      # Set the iv column on the model, whatever it is
+      #
+      def set_encryption_iv(iv)
+        return unless use_iv?
+        instance_variable_set( "@#{self.class.encryption_iv_column}".to_sym, iv )
+      end
+
+      ##
+      # If we have declared an IV column, we can use IV in encryption
+      #
+      def use_iv?
+        !self.class.encryption_iv_column.nil?
+      end
+
+      ##
+      # Return the correct OpenSSL Cipher object
+      #
+      def get_cipher(direction)
+        cipher = OpenSSL::Cipher.new(use_iv? ? CIPHER_IV : CIPHER_NO_IV)
+        case direction
+          when :encrypt then cipher.encrypt
+          when :decrypt then cipher.decrypt
+        end
+        cipher
+
+      rescue OpenSSL::Cipher::CipherError
+        raise Pod4::Pod4Error, $!
+      end
+
+      ##
+      # Encrypt / decrypt
+      #
+      def crypt(cipher, iv, string)
+        return string if use_iv? and iv.nil?
+        cipher.key = self.class.encryption_key
+        cipher.iv = iv if use_iv?
+        cipher.update(string) + cipher.final
+
+      rescue OpenSSL::Cipher::CipherError
+        raise Pod4::Pod4Error, $!
+      end
+
+    end # of InstanceMethods
+
+
+  end # of Encrypting
+
+end
+

data/lib/pod4/typecasting.rb

@@ -1,3 +1,5 @@
+#require 'BigDecimal'
+require 'time'
 require 'pod4/errors'
 require 'pod4/metaxing'
 
@@ -6,22 +8,111 @@ module Pod4
 
 
   ##
-  # A mixin to give you some more options to control how Pod4 maps the interface to the model.
+  # A mixin to give you some more options to control how Pod4 deals with data types.
   #
-  # Eventually we will actually have typecasting in here. For now all this allows you to do is
-  # enforce an encoding -- which will be of use if you are dealing with MSSQL, or with certain
-  # interfaces which appear to deal with the code page poorly:
+  # Example
+  # -------
   #
-  #     class FOo < Pod4::Model
+  #     class Foo < Pod4::Model
   #       include Pod4::TypeCasting
-  #
+  #    
+  #       class Interface < Pod4::SomeInterface
+  #         # blah blah blah
+  #       end
+  #       set_interface Interface.new($stuff)
+  #    
+  #       attr_columns :name, :issue, :created, :due, :last_update, :completed, :thing
+  #    
+  #       # Now the meat
   #       force_encoding Encoding::UTF-8
-  #
-  #       ...
+  #       typecast :issue,         as: Integer, strict: true
+  #       typecast :created, :due, as: Date
+  #       typecast :last_update,   as: Time
+  #       typecast :completed,     as: BigDecimal, ot_as: Float
+  #       typecast :thing,         use: mymethod
   #     end
   #
+  # So this adds two commands to the model DSL: force_encoding, and typecast. Both are optional.
+  #
+  # Force Encoding
+  # --------------
+  #
+  # Pass this a Ruby encoding, and it will call force the encoding of each incoming value from the
+  # database to match. It is to work around problems with some data sources like MSSQL, which may
+  # deal with encoding poorly.
+  #
+  # Typecasting
+  # -----------
+  #
+  # This has the syntax: `typecast <attr> [,...], <options>`.
+  #
+  # Options are `as:`, `ot_as:`, `strict:` and `use:`. You must specify either `as:` or `use:`.
+  #
+  # Valid types are BigDecimal, Float, Integer, Date, Time, and :boolean. 
+  #
+  # Changes to Behaviour of Model
+  # -----------------------------
+  #
+  # General: Any attributes named using `typecast` are set `attr_reader` if they are not already
+  # so. 
+  #
+  # `map_to_model`: incoming data from the data source is coerced to the given encoding if
+  # `force_encoding` has been used.
+  #
+  # `set()`: typecast attributes are cast as per their settings, or if they cannot be cast, are left
+  # alone. (Unless you have specified `strict: true`, in which case they are set to nil.)
+  #
+  # `to_ot()`: any typecast attributes with `ot_as` are cast that way in the outgoing OT, and set
+  # guard that way too (see Octothorpe#guard) to give a reasonable default value instead of nil.
+  #
+  # `map_to_interface()`: typecast attributes are cast as per their settings, or if they cannot be
+  # cast, are set to nil.
+  #
+  # Additional methods
+  # ------------------
+  #
+  # The following are provided:
+  #
+  # * `typecast?(:columnname, value)` returns true if the value can be cast; value defaults to the
+  #   column value if not given.
+  # 
+  # * `typecast(type, value, options)` returns a typecast value, or either the original value, or
+  # nil if options[:strict] is true.
+  # 
+  # * `guard(octothorpe)` sets guard conditions on the given octothorpe, based on the attributes
+  #   typecast knows about. If the value was nil, it will be a reasonable default for the type
+  #   instead.
+  #
+  # Custom Typecasting Methods
+  # --------------------------
+  #
+  # By specifying `use: my_method` you are telling Pod4 that you have a method that will return the
+  # typecast value for the type.  This method will be called as `my_method(value, options)`,
+  # where value is the value to be typecast, and options is the hash of options you specified for
+  # that column.  Pod4 will set the column to whatever your method returns.
+  #
+  # What you don't get
+  # ------------------
+  #
+  # None of this has any direct effect on validation, although of course we do provide methods such
+  # as `typecast?()` to specifically help you with validation.
+  #
+  # Naming an attribute using `typecast` does not automatically make is a Pod4 column; you need to
+  # use `attr_column`, just as in plain Pod4. Furthermore, *only* Pod4 columns can be named in the
+  # typecast command, although you can use the `typecast` instance method, etc., to help you roll
+  # your own typecasting for non-column attributes.
+  #
+  # Loss of information.  If your column is typecast to Integer, then setting it to 12.34 will not
+  # round it to 12. Likewise, I know that Time.to_date is a thing, but we don't support it.
+  #
+  # Protection from nil, except when using `ot_as:`. A column is always allowed to be nil,
+  # regardless of how it is typecast. (On the contrary: by forcing strict columns to nil if they
+  # fail typecasting, we help you validate.)
+  #
   module TypeCasting
 
+    TYPES = [ Date, Time, Integer, Float, BigDecimal, :boolean ]
+
     ##
     # A little bit of magic, for which I apologise. 
     #
@@ -46,8 +137,29 @@ module Pod4
       end
 
       def encoding; nil; end
-    end
-    ##
+
+      def typecast(*args)
+        options = args.pop
+        raise Pod4Error, "Bad Type" \
+          unless options.keys.include?(:use) || TYPES.include?(options[:as])
+
+        raise Pod4Error, "Bad Typecasting" unless options.is_a?(Hash) \
+                                               && options.keys.any?{|o| %i|as use|.include? o} \
+                                               && args.size >= 1
+
+        # Modify self.typecasts to look like: {foo: {as: Date}, bar: {as: Time, strict: true}, ...}
+        c = typecasts.dup
+        args.each do |f| 
+          raise Pod4Error, "Unknown column '#{f}'" unless columns.include?(f)
+          c[f] = options
+        end
+
+        define_class_method(:typecasts) {c}
+      end
+
+      def typecasts; {}; end
+
+    end # of ClassMethods
 
 
     module InstanceMethods
@@ -55,17 +167,171 @@ module Pod4
       def map_to_model(ot)
         enc = self.class.encoding
         
-        ot.each do |_,v| 
+        ot.each_value do |v|
           v.force_encoding(enc) if v.kind_of?(String) && enc
         end
 
         super(ot)
       end
 
-    end
-    ##
+      def set(ot)
+        hash = typecast_ot(ot)
+        super(ot.merge hash)
+      end
+
+      def map_to_interface
+        ot   = super
+        hash = typecast_ot(ot, strict: true)
+        ot.merge hash
+      end
+
+      def to_ot
+        ot  = super
+        ot2 = ot.merge typecast_ot_to_ot(ot)
+
+        self.class.typecasts.each do |fld, tc|
+          set_guard(ot2, fld, tc[:ot_as]) if tc[:ot_as]
+        end
+
+        ot2
+      end
+
+      ##
+      # Return thing cast to type. If opt[:strict] is true, then return nil if thing cannot be
+      # cast to type; otherwise return thing unchanged.
+      #
+      def typecast(type, thing, opt={})
+        # Nothing to do
+        return thing if type.is_a?(Class) && thing.is_a?(type)
+
+        # Nothing wrong with nil for our purposes; it's always allowed
+        return thing if thing.nil?
+
+        # For all current cases, attempting to typecast a blank string should return nil
+        return nil if thing =~ /\A\s*\Z/ 
+
+        # The order we try these in matters
+        return tc_bigdecimal(thing) if type == BigDecimal 
+        return tc_float(thing)      if type == Float      
+        return tc_integer(thing)    if type == Integer    
+        return tc_date(thing)       if type == Date       
+        return tc_time(thing)       if type == Time       
+        return tc_boolean(thing)    if type == :boolean   
+
+        fail Pod4Error, "Bad type passed to typecast()"
+      rescue ArgumentError
+        return (opt[:strict] ? nil : thing)
+      end
+
+      ## 
+      # Return true if the attribute can be cast to the given value.
+      # You must name an attribute you specified in a typecast declaration, or you will get an
+      # exception. 
+      # You may pass a value to test, or failing that, we take the current value of the attribute.
+      #
+      def typecast?(attr, val=nil)
+        fail Pod4Error, "Unknown column passed to typecast?()" \
+          unless (tc = self.class.typecasts[attr])
+
+        val = instance_variable_get("@#{attr}".to_sym) if val.nil?
+        !typecast_one(val, tc.merge(strict: true)).nil?
+      end
+
+      ## 
+      # set Octothorpe Guards for everything in the given OT, based on the typecast settings.
+      #
+      def guard(ot)
+        self.class.typecasts.each do |fld, tc|
+          type = tc[:ot_as] || tc[:as]
+          set_guard(ot, fld, type) if type
+        end
+      end
+
+      private
+
+      ## 
+      # Return a hash of changes for an OT based on our settings
+      #
+      def typecast_ot(ot, opts={})
+        hash = {}
+        ot.each do |k,v|
+          tc = self.class.typecasts[k]
+          hash[k] = typecast_one(v, tc.merge(opts)) if tc
+        end
+        hash
+      end
+
+      ##
+      # As typecast_ot, but this is a specific helper for to_ot
+      #
+      def typecast_ot_to_ot(ot)
+        hash = {}
+        ot.each do |k,v|
+          tc = self.class.typecasts[k]
+          hash[k] = (tc && tc[:ot_as]) ? typecast(tc[:ot_as], v) : v
+        end
+        hash
+      end
+
+      ## 
+      # Helper for typecast_ot: cast one attribute
+      #
+      def typecast_one(val, tc)
+        if tc[:use]
+          self.__send__(tc[:use], val, tc)
+        else
+          typecast(tc[:as], val, tc) 
+        end
+      end
+
+      ##
+      # Set the guard clause for one attribute
+      # Note that Time.new returns now, and Date.new returns some date in antiquity. We don't
+      # consider those helpful, so we give you 1900-1-1 in both cases
+      #
+      def set_guard(ot, fld, tc)
+        case tc.to_s
+          when "BigDecimal" then ot.guard(fld) { BigDecimal.new("0")  }
+          when "Float"      then ot.guard(fld) { Float(0)             }
+          when "Integer"    then ot.guard(fld) { Integer(0)           }
+          when "Date"       then ot.guard(fld) { Date.new(1900, 1, 1) }
+          when "Time"       then ot.guard(fld) { Time.new(1900, 1, 1) }
+          when "boolean"    then ot.guard(fld) { false                }
+        end
+      end
+
+      def tc_bigdecimal(thing)
+        Float(thing) # BigDecimal sucks at catching bad decimals
+        BigDecimal.new(thing.to_s)
+      end
+
+      def tc_float(thing)
+        Float(thing)
+      end
+
+      def tc_integer(thing)
+        Integer(thing.to_s, 10)
+      end
+
+      def tc_date(thing)
+        fail ArgumentError, "Can't cast Time to Date" if thing.is_a?(Time)
+        thing.respond_to?(:to_date) ? thing.to_date : Date.parse(thing.to_s)
+      end
+
+      def tc_time(thing)
+        thing.respond_to?(:to_time) ? thing.to_time : Time.parse(thing.to_s)
+      end
+
+      def tc_boolean(thing)
+        return thing if thing == true || thing == false
+        return true  if %w|true yes y on t 1|.include?(thing.to_s.downcase)
+        return false if %w|false no n off f 0|.include?(thing.to_s.downcase)
+        fail ArgumentError, "Cannot typecast string to Boolean"
+      end
+
+    end # of InstanceMethods
 
-  end
+  end # of TypeCasting
 
 
 end

data/lib/pod4/version.rb

@@ -1,3 +1,3 @@
 module Pod4 
-  VERSION = '0.9.3'
+  VERSION = '0.10.0'
 end

data/md/typecasting.md

@@ -0,0 +1,80 @@
+TypeCasting
+===========
+
+Example
+-------
+
+```
+require 'pod4'
+require 'pod4/someinterface'
+require 'pod4/typecasting'
+
+class Foo < Pod4::Model
+  include Pod4::TypeCasting
+
+  class Interface < Pod4::SomeInterface
+    # blah blah blah
+  end
+
+  set_interface Interface.new($stuff)
+
+  attr_columns :name, :issue, :created, :due, :last_update, :completed, :thing
+
+  # Now the meat
+  typecast :issue,         as: Integer
+  typecast :created, :due, as: Date
+  typecast :last_update,   as: Time
+  typecast :completed,     as: BigDecimal, ot_as: Float
+  typecast :thing,         use: mymethod
+end
+```
+
+What You Get
+------------
+
+### Every attribute named in a typecast gets:
+
+* An accessor. (Probably it already has one, if it is named in attr_columns, but it doesn't have to
+  be. Note, though, that we don't add the attribute to the column list and it does not get output
+  in to_ot by default.)
+
+* An attempt to force the value to that data type on set().  If the value cannot be coerced, it is
+  *untouched*. 
+
+* A second attempt to cast on to_interface(). This time, if the value cannot be coerced, it is set
+  to nil.
+
+* if the optional `ot_as` type is set, then we cast a third time in the `to_ot()` method;
+  additionally we guard the OT with the base type using Octothorpe.guard. Note that this only
+  effects to_ot().
+
+### Additionally the user can call these methods:
+
+* `typecast?(:columnname, value)` returns true if the value can be cast; value defaults to the
+  column value if not given.
+
+* `typecast(type, value, strict)` returns a typecast value, or either the original value, or nil if
+  strict is `:strict'.  
+
+* `guard(octothorpe)` will set guard conditions for nil values on the given octothorpe, based on
+  the attributes typecast knows about.
+
+### The following types will be supported:
+
+* Integer
+* BigDecimal
+* Float
+* Date
+* Time
+* :boolean
+
+Also: custom typecasting (`use: mymethod`, above). This must accept two parameters: the value, and
+an option hash.
+
+
+What You Don't Get
+------------------
+
+Validation. It's entirely up to you to decide how to validate and we won't second guess that.  But
+we do provide the `typecast?` method to help.
+