Module: X::Resources::Marshalling

Included in:
X::Resource
Defined in:
x-resources/lib/x/resources/marshalling.rb

Overview

The state of a resource Marshal and YAML write and read

Internal to x-resources: the methods it gives a resource, marshal_dump, marshal_load, encode_with, and init_with, are public API, but the module is only how they are given, and which classes include it can change within 1.x.

Instance Method Summary collapse

Instance Method Details

#encode_with(coder) ⇒ void

This method returns an undefined value.

Write the state Marshal writes as YAML, which leaves out the client

YAML reads no marshal_dump, and would write every instance variable, the client and its credentials among them, so a resource says how it is written: each part of the state Marshal writes, under its name.

Examples:

Write a user as YAML, as a queue writes the arguments of a job

YAML.dump(user)

Parameters:

  • coder (Psych::Coder) —

    the coder YAML writes the resource with



76
 
# File 'x-resources/lib/x/resources/marshalling.rb', line 76

def encode_with(coder) = YAML_KEYS.zip(marshal_dump) { |key, value| coder[key] = value }

#init_with(coder) ⇒ void

This method returns an undefined value.

Restore a resource YAML read, as Marshal restores one

It has no client, and so makes no request.

Examples:

Read a user written as YAML

YAML.unsafe_load(YAML.dump(user)).username # => "sferik"

Parameters:

  • coder (Psych::Coder) —

    the coder YAML read the resource with

Raises:



89
 
# File 'x-resources/lib/x/resources/marshalling.rb', line 89

def init_with(coder) = marshal_load(coder.map.values_at(*YAML_KEYS))

#marshal_dump ⇒ Array

The state Marshal writes, which leaves out the client

The client is left out, since it holds credentials and a connection. What is written is plain data, led by the number of its format, so that a resource written by one release of 1.x is read by a later one: its attributes, whether it is hydrated, and, of the response it came from, the included objects it refers to, and those they refer to in turn, the problems about any of them, and the query, so that the references it resolves, and the problems it and they report, are what they were, while the rest of the response is left out, however many other resources it held.

Examples:

Cache a user

Rails.cache.write("user", user)

Returns:

  • (Array) —

    the number of the format, then the state of the resource



40
41
42
43
 
# File 'x-resources/lib/x/resources/marshalling.rb', line 40

def marshal_dump
  data, problems, query = includes.state_of([self]) # steep:ignore NoMethod
  [MARSHAL_FORMAT, attrs, hydrated?, data, problems, query]
end

#marshal_load(state) ⇒ void

This method returns an undefined value.

Restore a resource Marshal read, which has no client and so makes no request

What Marshal reads is a client-less resource that answers its readers, resolves the references its response included, and reports its problems, as the resource that was written did, and raises from a hydrate, refresh, or collection that would make a request. It is hydrated if it was, and the query of its request asks for every field this release requests, so that one written before a minor release added to the fields is not.

Examples:

Read a cached user

Marshal.load(Marshal.dump(user)).username # => "sferik"

Parameters:

  • state (Array) —

    the state Marshal wrote

Raises:



58
59
60
61
62
63
64
 
# File 'x-resources/lib/x/resources/marshalling.rb', line 58

def marshal_load(state)
  format, attrs, hydrated, data, problems, query = state
  raise UnsupportedFormat, "#{self.class} reads format #{MARSHAL_FORMAT} of Marshal, not #{format.inspect}" unless MARSHAL_FORMAT.eql?(format)

  includes = Includes.new(data, problems:, query:)
  setup(attrs, client: nil, hydrated: includes.hydrated_as_read?(self.class, hydrated), includes:) # steep:ignore NoMethod
end