paquito 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fdea3e761f0c5cf3d5a99a42f31e55b645921e6597fb027c560de421b55f7ae3
+  data.tar.gz: f3dc6d6b15d149bb1d00115b79ef7f337af01197b5961a14fa9baead46e2586a
+SHA512:
+  metadata.gz: ac2d37fe39cace2096b041200eb2c2fac5fa2b6024747420a69645097642bce3ef35d66dce1c53d0ff801a921c46f84ca68fdb5a123ffd5c71e52f2a492bc0b8
+  data.tar.gz: e0e6e8329734bfed770fc1cf8b1c964e7c7902a55686d7182cd078c26a3255d4e7af91e17e2898e35ef9c3515df1d38c5243417d18190cd968f4232e85231e59

data/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  rubies:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [ ruby-head, '3.0', '2.7' ]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: |
+          rm Gemfile.lock
+          bundle install
+      - name: Run test
+        run: bundle exec rake
+      - name: Install gem
+        run: bundle exec rake install

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rubocop.yml

@@ -0,0 +1,5 @@
+inherit_gem:
+  rubocop-shopify: rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 2.7

data/Gemfile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in paquito.gemspec
+gemspec
+
+gem "msgpack", github: "msgpack/msgpack-ruby" # Waiting for release of https://github.com/msgpack/msgpack-ruby/pull/220
+
+gem "rake", "~> 13.0"
+gem "activesupport", ">= 7.0.0.alpha2"
+gem "activerecord", ">= 7.0.0.alpha2"
+gem "sqlite3"
+
+gem "minitest", "~> 5.0"
+
+gem "rubocop"
+gem "rubocop-shopify", "~> 2.0", require: false
+gem "byebug"
+
+gem "sorbet-runtime"

data/Gemfile.lock

@@ -0,0 +1,78 @@
+GIT
+  remote: https://github.com/msgpack/msgpack-ruby.git
+  revision: ea20842ea732f4d625fd30c7b8f67655d73652f2
+  specs:
+    msgpack (1.4.2)
+
+PATH
+  remote: .
+  specs:
+    paquito (0.1.0)
+      msgpack
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (7.0.0.alpha2)
+      activesupport (= 7.0.0.alpha2)
+    activerecord (7.0.0.alpha2)
+      activemodel (= 7.0.0.alpha2)
+      activesupport (= 7.0.0.alpha2)
+    activesupport (7.0.0.alpha2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    ast (2.4.2)
+    byebug (11.1.3)
+    concurrent-ruby (1.1.9)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    minitest (5.14.4)
+    parallel (1.21.0)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
+    rainbow (3.0.0)
+    rake (13.0.6)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rubocop (1.22.1)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.12.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.12.0)
+      parser (>= 3.0.1.1)
+    rubocop-shopify (2.3.0)
+      rubocop (~> 1.22)
+    ruby-progressbar (1.11.0)
+    sorbet-runtime (0.5.9209)
+    sqlite3 (1.4.2)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.1.0)
+
+PLATFORMS
+  ruby
+  x86_64-darwin-20
+  x86_64-linux
+
+DEPENDENCIES
+  activerecord (>= 7.0.0.alpha2)
+  activesupport (>= 7.0.0.alpha2)
+  byebug
+  minitest (~> 5.0)
+  msgpack!
+  paquito!
+  rake (~> 13.0)
+  rubocop
+  rubocop-shopify (~> 2.0)
+  sorbet-runtime
+  sqlite3
+
+BUNDLED WITH
+   2.2.22

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,175 @@
+# Paquito
+
+`Paquito` provies utility classes to define optimized and evolutive serializers.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'paquito'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install paquito
+
+## Usage
+
+### `chain`
+
+`Paquito::CoderChain` allows to combine two or more serializers into one.
+
+Example:
+
+```ruby
+compressed_yaml_coder = Paquito.chain(YAML, Zlib)
+payload = compressed_yaml_coder.dump({ foo: 42 }) # YAML compressed with gzip
+compressed_yaml_coder.load(payload) # => { foo: 42 }
+```
+
+### `ConditionalCompressor`
+
+`Paquito::ConditionalCompressor` compress payloads if they are over a defined size.
+
+Example:
+```ruby
+coder = Paquito::ConditionalCompressor.new(Zlib, 256)
+coder.dump("foo") # => "\x00foo"
+coder.dump("foo" * 500) # => "\x01<compressed-data....>"
+```
+
+### `SingleBytePrefixVersion`
+
+`Paquito::SingleBytePrefixVersion` prepends a version prefix to the payloads, which then allow to seemlessly transition from
+different serialization methods.
+
+The first argument is the current version used for newly generated payloads.
+
+Example:
+
+```ruby
+coder = Paquito::SingleBytePrefixVersion.new(1,
+  0 => YAML,
+  1 => JSON,
+  2 => MessagePack,
+)
+coder.dump([1]) # => "\x01[1]"
+coder.load("\x00---\n:foo: 42") # => { foo: 42 }
+```
+
+### `CommentPrefixVersion`
+
+Similar to the single byte prefix, but meant to be human readable and to allow for migrating unversionned payloads.
+
+Payload without a version prefix are assumed to be version `0`.
+
+The first argument is the current version used for newly generated payloads.
+
+Example:
+
+```ruby
+coder = Paquito::CommentPrefixVersion.new(1,
+  0 => YAML,
+  1 => JSON,
+)
+
+coder.load("---\n:foo: 42") # => { foo: 42 }
+coder.dump([1]) # => "#☠1☢\n[1]"
+```
+
+### `allow_nil`
+
+In some situation where you'd rather not serialize `nil`, you can use the `Paquito.allow_nil` shorthand:
+
+```ruby
+coder = Paquito.allow_nil(Marshal)
+coder.dump(nil) # => nil
+coder.load(nil) # => nil
+```
+
+### `TranslateErrors`
+
+If you do need to handle serialization or deserialization errors, for instance to fallback to acting like a cache miss,
+`Paquito::TranslateErrors` translate all underlying exceptions into `Paquito::Error` descendants.
+
+Example:
+
+```ruby
+coder = Paquito::TranslateErrors.new(Paquito::CoderChain.new(YAML, Zlib))
+coder.load("\x00") # => Paquito::UnpackError (buffer error)
+```
+
+### `CodecFactory`
+
+`Paquito::CodecFactory` is a utility facade to create advanced `MessagePack` factories with support for common Ruby
+and Rails types.
+
+Example
+```ruby
+coder = Paquito::CodecFactory.build([Symbol, Set])
+coder.load(coder.dump(%i(foo bar).to_set)) # => #<Set: {:foo, :bar}>
+```
+
+### `TypedStruct`
+
+`Paquito::TypedStruct` is a opt-in Sorbet runtime plugin that allows `T::Struct` classes to be serializable. You need to explicitly include the module in the `T::Struct` classes that you will be serializing.
+
+Example
+```ruby
+class MyStruct < T::Struct
+  include Paquito::TypedStruct
+
+  prop :foo, String
+  prop :bar, Integer
+end
+
+my_struct = MyStruct.new(foo: "foo", bar: 1)
+
+my_struct.as_pack # => [26450, "foo", 1]
+MyStruct.from_pack([26450, "foo", 1]) # => <MyStruct bar=1, foo="foo">
+```
+
+## Active Record utilities
+
+`paquito` doesn't not depend on `rails` nor any of it's componement, however it does provide some optional utilities for it.
+
+### `SerializedColumn`
+
+`Paquito::SerializedColumn` allows to decorate any encoder to behave like Rails's builtin `YAMLColumn`
+
+Example:
+
+```ruby
+class Shop < ActiveRecord::Base
+  serialize :settings, Paquito::SerializedColumn.new(
+    Paquito::CommentPrefixVersion.new(
+      1,
+      0 => YAML,
+      1 => Paquito::CodecFactory.build([Symbol]),
+    ),
+    Hash,
+    attribute_name: :settings,
+  )
+end
+
+Shop.new.settings # => {}
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/paquito.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+suites = [:vanilla, :activesupport, :activerecord]
+namespace :test do
+  suites.each do |suite|
+    Rake::TestTask.new(suite) do |t|
+      t.libs << "test/#{suite}"
+      t.libs << "lib"
+      t.test_files = FileList["test/#{suite}/**/*_test.rb"]
+    end
+  end
+end
+
+task test: suites.map { |s| "test:#{s}" }
+
+task default: :test

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "paquito"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/dev.yml

@@ -0,0 +1,12 @@
+name: paquito
+
+up:
+  - ruby:
+      version: 2.7.4
+  - bundler
+
+commands:
+  test:
+    syntax: ""
+    desc: 'run all the tests'
+    run: bundle exec rake test

data/lib/paquito/active_record_coder.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "paquito/errors"
+
+module Paquito
+  class ActiveRecordCoder
+    class << self
+      def dump(record)
+        instances = InstanceTracker.new
+        serialized_associations = serialize_associations(record, instances)
+        serialized_records = instances.map { |r| serialize_record(r) }
+        [serialized_associations, *serialized_records]
+      end
+
+      def load(payload)
+        instances = InstanceTracker.new
+        serialized_associations, *serialized_records = payload
+        serialized_records.each { |attrs| instances.push(deserialize_record(*attrs)) }
+        deserialize_associations(serialized_associations, instances)
+      end
+
+      private
+
+      # Records without associations, or which have already been visited before,
+      # are serialized by their id alone.
+      #
+      # Records with associations are serialized as a two-element array including
+      # their id and the record's association cache.
+      #
+      def serialize_associations(record, instances)
+        return unless record
+
+        if (id = instances.lookup(record))
+          payload = id
+        else
+          payload = instances.push(record)
+
+          cached_associations = record.class.reflect_on_all_associations.select do |reflection|
+            record.association_cached?(reflection.name)
+          end
+
+          unless cached_associations.empty?
+            serialized_associations = cached_associations.map do |reflection|
+              association = record.association(reflection.name)
+
+              serialized_target = if reflection.collection?
+                association.target.map { |target_record| serialize_associations(target_record, instances) }
+              else
+                serialize_associations(association.target, instances)
+              end
+
+              [reflection.name, serialized_target]
+            end
+
+            payload = [payload, serialized_associations]
+          end
+        end
+
+        payload
+      end
+
+      def deserialize_associations(payload, instances)
+        return unless payload
+
+        id, associations = payload
+        record = instances.fetch(id)
+
+        associations&.each do |name, serialized_target|
+          begin
+            association = record.association(name)
+          rescue ActiveRecord::AssociationNotFoundError
+            raise AssociationMissingError, "undefined association: #{name}"
+          end
+
+          target = if association.reflection.collection?
+            serialized_target.map! { |serialized_record| deserialize_associations(serialized_record, instances) }
+          else
+            deserialize_associations(serialized_target, instances)
+          end
+
+          association.target = target
+        end
+
+        record
+      end
+
+      def serialize_record(record)
+        [record.class.name, attributes_for_database(record)]
+      end
+
+      def attributes_for_database(record)
+        attributes = record.attributes_for_database
+        attributes.transform_values! { |attr| attr.is_a?(::ActiveModel::Type::Binary::Data) ? attr.to_s : attr }
+        attributes
+      end
+
+      def deserialize_record(class_name, attributes_from_database)
+        begin
+          klass = Object.const_get(class_name)
+        rescue NameError
+          raise ClassMissingError, "undefined class: #{class_name}"
+        end
+        klass.instantiate(attributes_from_database)
+      end
+    end
+
+    class Error < ::Paquito::Error
+    end
+
+    class ClassMissingError < Error
+    end
+
+    class AssociationMissingError < Error
+    end
+
+    class InstanceTracker
+      def initialize
+        @instances = []
+        @ids = {}.compare_by_identity
+      end
+
+      def map(...)
+        @instances.map(...)
+      end
+
+      def fetch(...)
+        @instances.fetch(...)
+      end
+
+      def push(instance)
+        id = @ids[instance] = @instances.size
+        @instances << instance
+        id
+      end
+
+      def lookup(instance)
+        @ids[instance]
+      end
+    end
+  end
+end

data/lib/paquito/allow_nil.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Paquito
+  class AllowNil
+    def initialize(coder)
+      @coder = Paquito.cast(coder)
+    end
+
+    def dump(object)
+      return nil if object.nil?
+      @coder.dump(object)
+    end
+
+    def load(payload)
+      return nil if payload.nil?
+      @coder.load(payload)
+    end
+  end
+end

data/lib/paquito/codec_factory.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "paquito/types"
+require "paquito/coder_chain"
+
+module Paquito
+  class CodecFactory
+    def self.build(types, freeze: false, serializable_type: false)
+      factory =
+        if types.empty? && !serializable_type
+          MessagePack
+        else
+          MessagePack::Factory.new
+        end
+      Types.register(factory, types) unless types.empty?
+      Types.register_serializable_type(factory) if serializable_type
+      MessagePackCodec.new(factory, freeze: freeze)
+    end
+
+    class MessagePackCodec
+      def initialize(factory, freeze: false)
+        @factory = factory
+        @freeze = freeze
+      end
+
+      def dump(object)
+        @factory.dump(object)
+      rescue NoMethodError => error
+        raise PackError.new(error.message, error.receiver)
+      end
+
+      def load(payload)
+        @factory.load(payload, freeze: @freeze)
+      rescue MessagePack::UnpackError => error
+        raise UnpackError, error.message
+      end
+    end
+  end
+end

data/lib/paquito/coder_chain.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Paquito
+  class CoderChain
+    def initialize(*coders)
+      @coders = coders.flatten.map { |c| Paquito.cast(c) }
+    end
+
+    def dump(object)
+      payload = object
+      @coders.each { |c| payload = c.dump(payload) }
+      payload
+    end
+
+    def load(payload)
+      object = payload
+      @coders.reverse_each { |c| object = c.load(object) }
+      object
+    end
+  end
+end

data/lib/paquito/comment_prefix_version.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Paquito
+  class CommentPrefixVersion
+    PREFIX = "#\u2620"
+    SUFFIX = "\u2622\n"
+    VERSION_POSITION = PREFIX.bytesize
+
+    HEADER_SLICE = (0..(PREFIX.bytesize + SUFFIX.bytesize))
+    PAYLOAD_SLICE = (PREFIX.bytesize + 1 + SUFFIX.bytesize)..-1
+    DEFAULT_VERSION = 0
+
+    def initialize(current_version, coders)
+      unless (0..9).cover?(current_version) && coders.keys.all? { |version| (0..9).cover?(version) }
+        raise ArgumentError, "CommentPrefixVersion versions must be between 0 and 9"
+      end
+
+      @current_version = current_version
+      @coders = coders.transform_values { |c| Paquito.cast(c) }.freeze
+      @current_coder = coders.fetch(current_version)
+    end
+
+    def dump(object)
+      prefix = +"#{PREFIX}#{@current_version}#{SUFFIX}"
+      payload = @current_coder.dump(object)
+      if payload.encoding == Encoding::BINARY
+        prefix.b << payload
+      else
+        prefix << payload
+      end
+    end
+
+    def load(payload)
+      payload_version, serial = extract_version(payload)
+
+      coder = @coders.fetch(payload_version) do
+        raise UnsupportedCodec, "Unsupported packer version #{payload_version}"
+      end
+      coder.load(serial)
+    end
+
+    private
+
+    def extract_version(serial)
+      header = serial.byteslice(HEADER_SLICE)&.force_encoding(Encoding::UTF_8)
+      unless header.start_with?(PREFIX) && header.end_with?(SUFFIX)
+        return [DEFAULT_VERSION, serial]
+      end
+
+      version = header.getbyte(VERSION_POSITION) - 48 # ASCII byte to number
+      [version, serial.byteslice(PAYLOAD_SLICE) || ""]
+    end
+  end
+end