Class: Stripe::StripeObject

Inherits:

Object

Object
Stripe::StripeObject

show all

Includes:: Enumerable

Defined in:: lib/stripe/stripe_object.rb

Direct Known Subclasses

Constant Summary collapse

RESERVED_FIELD_NAMES = When designing APIs, we now make a conscious effort server-side to avoid naming fields after important built-ins in various languages (e.g. class, method, etc.). However, a long time ago we made the mistake (either consciously or by accident) of initializing our ‘metadata` fields as instances of `StripeObject`, and metadata can have a wide range of different keys defined in it. This is somewhat a convenient in that it allows users to access data like `obj.metadata.my_field`, but is almost certainly not worth the cost. Naming metadata fields bad things like ‘class` causes `initialize_from` to produce strange results, so we ban known offenders here. In a future major version we should consider leaving ‘metadata` as a hash and forcing people to access it with `obj.metadata` because the potential for trouble is just too high. For now, reserve names.

[
  :class,
].freeze

@@permanent_attributes = rubocop:disable Style/ClassVars

Set.new([:id])

Instance Attribute Summary collapse

#last_response ⇒ Object readonly

Returns the value of attribute last_response.

Class Method Summary collapse

.additive_object_param(name) ⇒ Object

Sets the given parameter name to one which is known to be an additive object.
.additive_object_param?(name) ⇒ Boolean

Returns whether the given name is an additive object parameter.
.construct_from(values, opts = {}, last_response = nil, api_mode = :v1, requestor = nil) ⇒ Object
.protected_fields ⇒ Object

A protected field is one that doesn’t get an accessor assigned to it (i.e. ‘obj.public = …`) and one which is not allowed to be updated via the class level `Model.update(id, { … })`.

Instance Method Summary collapse

#==(other) ⇒ Object

Determines the equality of two Stripe objects.
#[](key) ⇒ Object
#[]=(key, value) ⇒ Object
#as_json(*opts) ⇒ Object
#deleted? ⇒ Boolean

Indicates whether or not the resource has been deleted on the server.
#dirty! ⇒ Object

Sets all keys within the StripeObject as unsaved so that they will be included with an update when #serialize_params is called.
#each(&blk) ⇒ Object
#eql?(other) ⇒ Boolean

Hash equality.
#hash ⇒ Object

As with equality in ‘#==` and `#eql?`, we hash two Stripe objects to the same value if they’re equivalent objects.
#initialize(id = nil, opts = {}, api_mode = :v1, requestor = nil) ⇒ StripeObject constructor

A new instance of StripeObject.
#inspect ⇒ Object
#keys ⇒ Object
#marshal_dump ⇒ Object

Implements custom encoding for Ruby’s Marshal.
#marshal_load(data, api_mode: :v1) ⇒ Object

Implements custom decoding for Ruby’s Marshal.
#serialize_params(options = {}) ⇒ Object
#to_hash ⇒ Object
#to_json(*_opts) ⇒ Object
#to_s(*_args) ⇒ Object
#update_attributes(values, opts = {}, dirty: true) ⇒ Object

Mass assigns attributes on the model.
#values ⇒ Object

Constructor Details

#initialize(id = nil, opts = {}, api_mode = :v1, requestor = nil) ⇒ `StripeObject`

Returns a new instance of StripeObject.

# File 'lib/stripe/stripe_object.rb', line 75

def initialize(id = nil, opts = {}, api_mode = :v1, requestor = nil)
  @api_mode = api_mode
  id, @retrieve_params = Util.normalize_id(id)
  @opts = Util.normalize_opts(opts)
  @original_values = {}
  @values = {}
  # This really belongs in APIResource, but not putting it there allows us
  # to have a unified inspect method
  @unsaved_values = Set.new
  @transient_values = Set.new
  @values[:id] = id if id
  @id = id
  @last_response = nil
  @requestor = requestor || APIRequestor.active_requestor
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args) ⇒ `Object` (protected)

Disabling the cop because it’s confused by the fact that the methods are protected, but we do define ‘#respond_to_missing?` just below. Hopefully this is fixed in more recent Rubocop versions.

# File 'lib/stripe/stripe_object.rb', line 391

protected def method_missing(name, *args)
  # TODO: only allow setting in updateable classes.
  if name.to_s.end_with?("=")
    attr = name.to_s[0...-1].to_sym

    # Pull out the assigned value. This is only used in the case of a
    # boolean value to add a question mark accessor (i.e. `foo?`) for
    # convenience.
    val = args.first

    # the second argument is only required when adding boolean accessors
    add_accessors([attr], attr => val)

    begin
      mth = method(name)
    rescue NameError
      raise NoMethodError,
            "Cannot set #{attr} on this object. HINT: you can't set: " \
            "#{@@permanent_attributes.to_a.join(', ')}"
    end
    return mth.call(args[0])
  elsif @values.key?(name)
    return @values[name]
  end

  begin
    super
  rescue NoMethodError => e
    # If we notice the accessed name of our set of transient values we can
    # give the user a slightly more helpful error message. If not, just
    # raise right away.
    raise unless @transient_values.include?(name)

    raise NoMethodError,
          e.message + ".  HINT: The '#{name}' attribute was set in the " \
                      "past, however.  It was then wiped when refreshing the object " \
                      "with the result returned by Stripe's API, probably as a " \
                      "result of a save().  The attributes currently available on " \
                      "this object are: #{@values.keys.join(', ')}"
  end
end

Instance Attribute Details

#last_response ⇒ `Object` (readonly)

Returns the value of attribute last_response.



7
8
9

# File 'lib/stripe/stripe_object.rb', line 7

def last_response
  @last_response
end

Class Method Details

.additive_object_param(name) ⇒ `Object`

Sets the given parameter name to one which is known to be an additive object.

Additive objects are subobjects in the API that don’t have the same semantics as most subobjects, which are fully replaced when they’re set. This is best illustrated by example. The ‘source` parameter sent when updating a subscription is not additive; if we set it:

source[object]=card&source[number]=123

We expect the old ‘source` object to have been overwritten completely. If the previous source had an `address_state` key associated with it and we didn’t send one this time, that value of ‘address_state` is gone.

By contrast, additive objects are those that will have new data added to them while keeping any existing data in place. The only known case of its use is for ‘metadata`, but it could in theory be more general. As an example, say we have a `metadata` object that looks like this on the server side:

metadata = { old: "old_value" }

If we update the object with ‘metadata=new_value`, the server side object now has both fields:

metadata = { old: "old_value", new: "new_value" }

This is okay in itself because usually users will want to treat it as additive:

obj.metadata[:new] = "new_value"
obj.save

However, in other cases, they may want to replace the entire existing contents:

obj.metadata = { new: "new_value" }
obj.save

This is where things get a little bit tricky because in order to clear any old keys that may have existed, we actually have to send an explicit empty string to the server. So the operation above would have to send this form to get the intended behavior:

metadata[old]=&metadata[new]=new_value

This method allows us to track which parameters are considered additive, and lets us behave correctly where appropriate when serializing parameters to be sent.

# File 'lib/stripe/stripe_object.rb', line 63

def self.additive_object_param(name)
  @additive_params ||= Set.new
  @additive_params << name
end

.additive_object_param?(name) ⇒ `Boolean`

Returns whether the given name is an additive object parameter. See ‘.additive_object_param` for details.

Returns:

(Boolean)

# File 'lib/stripe/stripe_object.rb', line 70

def self.additive_object_param?(name)
  @additive_params ||= Set.new
  @additive_params.include?(name)
end

.construct_from(values, opts = {}, last_response = nil, api_mode = :v1, requestor = nil) ⇒ `Object`

# File 'lib/stripe/stripe_object.rb', line 91

def self.construct_from(values, opts = {}, last_response = nil, api_mode = :v1, requestor = nil)
  values = Stripe::Util.symbolize_names(values)

  # work around protected #initialize_from for now
  new(values[:id]).send(:initialize_from, values, opts, last_response, api_mode: api_mode, requestor: requestor)
end

.protected_fields ⇒ `Object`

A protected field is one that doesn’t get an accessor assigned to it (i.e. ‘obj.public = …`) and one which is not allowed to be updated via the class level `Model.update(id, { … })`.



274
275
276

# File 'lib/stripe/stripe_object.rb', line 274

def self.protected_fields
  []
end

Instance Method Details

#==(other) ⇒ `Object`

Determines the equality of two Stripe objects. Stripe objects are considered to be equal if they have the same set of values and each one of those values is the same.

# File 'lib/stripe/stripe_object.rb', line 101

def ==(other)
  other.is_a?(StripeObject) &&
    @values == other.instance_variable_get(:@values)
end

#[](key) ⇒ `Object`



163
164
165

# File 'lib/stripe/stripe_object.rb', line 163

def [](key)
  @values[key.to_sym]
end

#[]=(key, value) ⇒ `Object`



167
168
169

# File 'lib/stripe/stripe_object.rb', line 167

def []=(key, value)
  send(:"#{key}=", value)
end

#as_json(*opts) ⇒ `Object`



184
185
186

# File 'lib/stripe/stripe_object.rb', line 184

def as_json(*opts)
  @values.as_json(*opts)
end

#deleted? ⇒ `Boolean`

Indicates whether or not the resource has been deleted on the server. Note that some, but not all, resources can indicate whether they have been deleted.

Returns:

(Boolean)



122
123
124

# File 'lib/stripe/stripe_object.rb', line 122

def deleted?
  @values.fetch(:deleted, false)
end

#dirty! ⇒ `Object`

Sets all keys within the StripeObject as unsaved so that they will be included with an update when #serialize_params is called. This method is also recursive, so any StripeObjects contained as values or which are values in a tenant array are also marked as dirty.

# File 'lib/stripe/stripe_object.rb', line 213

def dirty!
  @unsaved_values = Set.new(@values.keys)
  @values.each_value do |v|
    dirty_value!(v)
  end
end

#each(&blk) ⇒ `Object`



205
206
207

# File 'lib/stripe/stripe_object.rb', line 205

def each(&blk)
  @values.each(&blk)
end

#eql?(other) ⇒ `Boolean`

Hash equality. As with ‘#==`, we consider two equivalent Stripe objects equal.

Returns:

(Boolean)

# File 'lib/stripe/stripe_object.rb', line 108

def eql?(other)
  # Defer to the implementation on `#==`.
  self == other
end

#hash ⇒ `Object`

As with equality in ‘#==` and `#eql?`, we hash two Stripe objects to the same value if they’re equivalent objects.



115
116
117

# File 'lib/stripe/stripe_object.rb', line 115

def hash
  @values.hash
end

#inspect ⇒ `Object`

# File 'lib/stripe/stripe_object.rb', line 130

def inspect
  id_string = respond_to?(:id) && !id.nil? ? " id=#{id}" : ""
  "#<#{self.class}:0x#{object_id.to_s(16)}#{id_string}> JSON: " +
    JSON.pretty_generate(@values)
end

#keys ⇒ `Object`



171
172
173

# File 'lib/stripe/stripe_object.rb', line 171

def keys
  @values.keys
end

#marshal_dump ⇒ `Object`

Implements custom encoding for Ruby’s Marshal. The data produced by this method should be comprehendable by #marshal_load.

This allows us to remove certain features that cannot or should not be serialized.

# File 'lib/stripe/stripe_object.rb', line 225

def marshal_dump
  # The APIRequestor instance in @opts is not serializable and is not
  # really a property of the StripeObject, so we exclude it when
  # dumping
  opts = @opts.clone

  # TODO: (major) Remove the :client option. This is not explicitly supported as a user-specified option.
  opts.delete(:client)
  [@values, opts]
end

#marshal_load(data, api_mode: :v1) ⇒ `Object`

Implements custom decoding for Ruby’s Marshal. Consumes data that’s produced by #marshal_dump.

# File 'lib/stripe/stripe_object.rb', line 238

def marshal_load(data, api_mode: :v1)
  values, opts = data
  initialize(values[:id], api_mode: api_mode)
  initialize_from(values, opts, api_mode: api_mode, requestor: @requestor)
end

#serialize_params(options = {}) ⇒ `Object`

# File 'lib/stripe/stripe_object.rb', line 244

def serialize_params(options = {})
  update_hash = {}

  @values.each do |k, v|
    # There are a few reasons that we may want to add in a parameter for
    # update:
    #
    #   1. The `force` option has been set.
    #   2. We know that it was modified.
    #   3. Its value is a StripeObject. A StripeObject may contain modified
    #      values within in that its parent StripeObject doesn't know about.
    #
    unsaved = @unsaved_values.include?(k)
    next unless options[:force] || unsaved || v.is_a?(StripeObject)

    update_hash[k.to_sym] = serialize_params_value(
      @values[k], @original_values[k], unsaved, options[:force], key: k
    )
  end

  # a `nil` that makes it out of `#serialize_params_value` signals an empty
  # value that we shouldn't appear in the serialized form of the object
  update_hash.reject! { |_, v| v.nil? }

  update_hash
end

#to_hash ⇒ `Object`

# File 'lib/stripe/stripe_object.rb', line 188

def to_hash
  maybe_to_hash = lambda do |value|
    return nil if value.nil?

    value.respond_to?(:to_hash) ? value.to_hash : value
  end

  @values.each_with_object({}) do |(key, value), acc|
    acc[key] = case value
               when Array
                 value.map(&maybe_to_hash)
               else
                 maybe_to_hash.call(value)
               end
  end
end

#to_json(*_opts) ⇒ `Object`

# File 'lib/stripe/stripe_object.rb', line 179

def to_json(*_opts)
  # TODO: pass opts to JSON.generate?
  JSON.generate(@values)
end

#to_s(*_args) ⇒ `Object`



126
127
128

# File 'lib/stripe/stripe_object.rb', line 126

def to_s(*_args)
  JSON.pretty_generate(to_hash)
end

#update_attributes(values, opts = {}, dirty: true) ⇒ `Object`

Mass assigns attributes on the model.

This is a version of update_attributes that takes some extra options for internal use.

Attributes

values - Hash of values to use to update the current attributes of the object. If you are on ruby 2.7 or higher make sure to wrap in curly braces to be ruby 3 compatible.
opts - Options for StripeObject like an API key that will be reused on subsequent API calls.

Options

:dirty - Whether values should be initiated as “dirty” (unsaved) and which applies only to new StripeObjects being initiated under this StripeObject. Defaults to true.

# File 'lib/stripe/stripe_object.rb', line 154

def update_attributes(values, opts = {}, dirty: true)
  values.each do |k, v|
    add_accessors([k], values) unless metaclass.method_defined?(k.to_sym)
    @values[k] = Util.convert_to_stripe_object(v, opts, api_mode: @api_mode, requestor: @requestor)
    dirty_value!(@values[k]) if dirty
    @unsaved_values.add(k)
  end
end

#values ⇒ `Object`



175
176
177

# File 'lib/stripe/stripe_object.rb', line 175

def values
  @values.values
end

Class: Stripe::StripeObject

Direct Known Subclasses

Constant Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id = nil, opts = {}, api_mode = :v1, requestor = nil) ⇒ StripeObject

Dynamic Method Handling

#method_missing(name, *args) ⇒ Object (protected)

Instance Attribute Details

#last_response ⇒ Object (readonly)

Class Method Details

.additive_object_param(name) ⇒ Object

.additive_object_param?(name) ⇒ Boolean

.construct_from(values, opts = {}, last_response = nil, api_mode = :v1, requestor = nil) ⇒ Object

.protected_fields ⇒ Object

Instance Method Details

#==(other) ⇒ Object

#[](key) ⇒ Object

#[]=(key, value) ⇒ Object

#as_json(*opts) ⇒ Object

#deleted? ⇒ Boolean

#dirty! ⇒ Object

#each(&blk) ⇒ Object

#eql?(other) ⇒ Boolean

#hash ⇒ Object

#inspect ⇒ Object

#keys ⇒ Object

#marshal_dump ⇒ Object

#marshal_load(data, api_mode: :v1) ⇒ Object

#serialize_params(options = {}) ⇒ Object

#to_hash ⇒ Object

#to_json(*_opts) ⇒ Object

#to_s(*_args) ⇒ Object

#update_attributes(values, opts = {}, dirty: true) ⇒ Object

Attributes

Options

#values ⇒ Object

#initialize(id = nil, opts = {}, api_mode = :v1, requestor = nil) ⇒ `StripeObject`

#method_missing(name, *args) ⇒ `Object` (protected)

#last_response ⇒ `Object` (readonly)

.additive_object_param(name) ⇒ `Object`

.additive_object_param?(name) ⇒ `Boolean`

.construct_from(values, opts = {}, last_response = nil, api_mode = :v1, requestor = nil) ⇒ `Object`

.protected_fields ⇒ `Object`

#==(other) ⇒ `Object`

#[](key) ⇒ `Object`

#[]=(key, value) ⇒ `Object`

#as_json(*opts) ⇒ `Object`

#deleted? ⇒ `Boolean`

#dirty! ⇒ `Object`

#each(&blk) ⇒ `Object`

#eql?(other) ⇒ `Boolean`

#hash ⇒ `Object`

#inspect ⇒ `Object`

#keys ⇒ `Object`

#marshal_dump ⇒ `Object`

#marshal_load(data, api_mode: :v1) ⇒ `Object`

#serialize_params(options = {}) ⇒ `Object`

#to_hash ⇒ `Object`

#to_json(*_opts) ⇒ `Object`

#to_s(*_args) ⇒ `Object`

#update_attributes(values, opts = {}, dirty: true) ⇒ `Object`

#values ⇒ `Object`