internal_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1beab71c3746aca2c7edab9b64c200b5242e278ae99066ae2dcbc3e1600f1736
+  data.tar.gz: 2157b3450386d5b938f9eaf3eda39afa117fbff7d316a9554695ec49ffb144c7
+SHA512:
+  metadata.gz: 1d3ffa8c4e28c54c87b34900a164e2ecf1effe6678abeef87a103676283bf82d5886643b1b6ce886c0d0fc2933ccb3421a9806f44e914702f50d2dfff4cbd1df
+  data.tar.gz: 6f49f5eac3cb632817fabc03a7b041bc55db12e1cebdd5aec2b831754933dfe33f8c8a94e5ed0f476b659de056ffabde33c3e64aa5e209e199c462e5c3f62d23

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock
+.ruby-version

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,2 @@
+Style/ModuleFunction:
+  EnforcedStyle: extend_self

data/.travis.yml

@@ -0,0 +1,8 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.5.1
+before_install: gem install bundler -v 2.0.1
+script: bundle && bundle exec rake

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at github@jackcanty.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in internal_api.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Jack Danger
+
+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,85 @@
+# Ruby internal_api
+
+This is a gem for decomposing monolithic Rails apps. It allows you to specify an internal class or module that serves as the internal api for another class or module.
+
+Example:
+
+```ruby
+# Any class or module can be the interface for a portion of your app.
+# Imagine trying to collect all payment-related code in your app such that you
+# can guarantee none of it used except in the way you expect.
+#
+# You'll want to somehow encapsulate your models
+class PaymentRecord < ActiveRecord::Base
+  internal_api PaymentApi
+end
+
+# And any helper modules or classes
+module Payments
+  class Issue
+    internal_api PaymentApi
+  end
+end
+
+# And all you need is some object that you specify as the internal_api for all your code.
+module PaymentApi
+  def charge(amount_cents, options = {})
+    # This is whatever bespoke, ugly code you've inherited in your existing app.
+    record = PaymentRecord.create(amount_cents)
+    issue = Payments::Issue.new(record).complete!
+    log(issue)
+  end
+end
+
+# So when someone adds a new dependency to your internal code they fail their unit tests:
+module Onboarding
+  def self.complete!(user)
+    PaymentRecord.create(1_00, type: auth) 
+    # other onboarding stuff
+  end
+end
+Onboarding.complete(@user) #! Only `PaymentApi` methods can execute PaymentApi code.
+```
+
+The `internal_api` call rewrites the public methods on your internal code to
+ensure that it can only be called if `PaymentApi` is somewhere in the call
+stack. This allows you to hide an entire portion of your application behind an
+interface of some kind and have confidence it's reasonable well encapsulated.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'internal_api'
+```
+
+## Performance
+
+This API enforcement is purely dyamic - `internal_api` modified the runtime
+execution of code and checks for correct access patterns. This has a nonzero
+but completely negligible impact on performance and therefore can safely be run
+in production.
+
+If you come from a Java background you may be used to thinking of backtraces as
+very expensive. In Ruby they're quite cheap - the backtrace is always available
+in memory and accessing it only requires [turning](https://github.com/ruby/ruby/blob/c3cf1ef9bbacac6ae5abc99046db173e258dc7ca/vm_backtrace.c#L549-L566) the C stack into (simple) Ruby
+objects.
+
+Constructing a single backtrace in running production code takes only a few microseconds on any
+modern CPU:
+
+    >> Benchmark.measure { 1_000_000.times { Kernel.caller_locations }}.real
+    => 5.190758000011556
+
+## Contributing
+
+Patches welcome, forks celebrated. This project is a safe, welcoming space for collaboration, and contributors will adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the InternalApi project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/internal_api/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop)
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[rubocop spec]

data/VERSION

@@ -0,0 +1 @@
+0.1.0

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/internal_api.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'internal_api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'internal_api'
+  spec.version       = InternalApi::VERSION
+  spec.authors       = ['Jack Danger']
+  spec.email         = ['github@jackcanty.com']
+
+  spec.summary       = 'Carve up your Rails monolith via internal APIs'
+  spec.description   = 'Create code boundaries within your Rails monolith'
+  spec.homepage      = 'https://github.com/JackDanger/ruby_internal_api'
+  spec.license       = 'MIT'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added
+  # into git.
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'method_source'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'pry-byebug'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+end

data/lib/internal_api.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'internal_api/version'
+require 'internal_api/full_method_source_location'
+require 'internal_api/rewriter'
+
+# The InternalApi module provides one public method (`.internal_api`) available
+# on any Ruby module.
+# This method takes as its single argument any object has public methods. When
+# called, the (public) methods of the caller will no longer be directly
+# accessible.
+#
+# This is deliberately designed to not depend on any gems, C-extensions, or any
+# Ruby features specific to a minor version.
+module InternalApi
+  extend self
+
+  LoaderMutex = Mutex.new
+
+  # ViolationError is raised when protected code is called from code not behind
+  # the internal api
+  class ViolationError < StandardError; end
+
+  # This is the only public API method
+  module RubyCoreExtension
+    def internal_api(protector)
+      InternalApi.protect(self, protector)
+    end
+  end
+
+  # Rewrites all public methods on the protectee (the Ruby class or module that
+  # received the 'internal_api' message), replacing them with a method that
+  # checks the backtrace and ensures at least one line matches one of the
+  # public methods of the protector.
+  def protect(protectee, protector)
+    calculate_public_methods!(protector)
+
+    # Extract the eigenclass of any object
+    # https://medium.com/@ethan.reid.roberts/rubys-anonymous-eigenclass-putting-the-ei-in-team-ebc1e8f8d668
+    eigenclass = (class << protectee; self; end)
+
+    # Rewrite future public singleton methods
+    Rewriter.add_singleton_rewrite_hooks!(protectee, protector)
+    # Rewrite eigenclass' future public instance methods
+    Rewriter.add_instance_rewrite_hooks!(eigenclass, protector)
+    # Rewrite eigenclass' future public singleton methods
+    Rewriter.add_singleton_rewrite_hooks!(eigenclass, protector)
+  end
+
+  def check_caller!(protector)
+    allowed_caller_methods = InternalApi.public_method_cache[protector]
+    # NB: `caller` is much slower than `caller_locations`
+    caller_locations.each do |location|
+      # This calculation is quadratic but as the backtrace is finite and these
+      # comparisons take only tens of nanoseconds each this is fast enough for
+      # production use.
+      allowed_caller_methods.each do |path, range|
+        if location.path == path && range.include?(location.lineno)
+          return path, range
+        end
+      end
+    end
+    raise_violation!(caller_locations[1].label, protector)
+  end
+
+  def rewrite_method!(protectee, internal_method, protector)
+    protectee.instance_eval do
+      # We create a new pointer to the original method
+      alias_method "_internal_api_#{internal_method}", internal_method
+
+      # And overwrite it
+      define_method internal_method do |*args, &block|
+        InternalApi.check_caller!(protector)
+        send("_internal_api_#{internal_method}", *args, &block)
+      end
+    end
+  end
+
+  def public_method_cache
+    @public_method_cache ||= {}
+  end
+
+  def debug(line)
+    puts "InternalApi: #{line}" if $DEBUG
+  end
+
+  private
+
+  def raise_violation!(label, protector)
+    message = "#{label.inspect} is protected by `#{protector.name}`" \
+              " and can only execute when a `#{protector.name}`" \
+              ' method is in the backtrace'
+    raise InternalApi::ViolationError, message
+  end
+
+  def calculate_public_methods!(mod)
+    LoaderMutex.synchronize do
+      return if InternalApi.public_method_cache.key?(mod)
+
+      # We cache the public methods because this requires a fairly exhaustive,
+      # recursive lookup of Ruby method hierarchy to perform:
+      #
+      # https://github.com/ruby/ruby/blob/c3cf1ef9bbacac6ae5abc99046db173e258dc7ca/class.c#L1206-L1238
+      #
+      # > Benchmark.measure { 10_000.times { Object.new }}.real
+      # => 0.0033939999993890524
+      # >> Benchmark.measure { 10_000.times { Object.public_methods }}.real
+      # => 0.1327720000408589800
+      #
+      # It's up to the user to avoid adding new public methods to the protected
+      # code after app initialization.
+
+      source_ranges = FullMethodSourceLocation.public_method_source_ranges(mod)
+      unless source_ranges
+        raise InternalApi::UnreachableCodeError,
+              "#{self} is protected by #{protector}," \
+              ' which has no public methods'
+      end
+
+      InternalApi.public_method_cache[mod] = source_ranges
+    end
+  end
+end
+
+# Make this generally available
+Module.include InternalApi::RubyCoreExtension
+Class.include InternalApi::RubyCoreExtension
+
+# Time to #dogfood.
+# Protect the internal parts of InternalAPI
+# InternalApi.internal_api(InternalApi::RubyCoreExtension)

data/lib/internal_api/full_method_source_location.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'method_source'
+module InternalApi
+  # Ruby gives us the start location of a method but not the end. We need to
+  # know the full range so we can verify any calls made anywhere in a method
+  # have originated from that method.
+  #
+  # We lean on the MethodSource gem (the library underneath Pry's method
+  # inspection) for this as it does some wild trickery with attempting to
+  # parse raw Ruby code without actually using a parser.
+  module FullMethodSourceLocation
+    extend self
+
+    def range(method)
+      source_location = method.source_location
+      return unless source_location
+
+      path, start = source_location
+
+      source = MethodSource.source_helper(source_location)
+      [path, (start..(start + source.lines.size - 1))]
+    end
+
+    # Find the file path and the start and end line numbers of all public class
+    # methods and public instance methods
+    def public_method_source_ranges(mod)
+      class_ranges = mod.public_methods(false).map do |m|
+        FullMethodSourceLocation.range(mod.method(m))
+      end.compact
+      instance_ranges = mod.public_instance_methods(false).map do |m|
+        FullMethodSourceLocation.range(mod.instance_method(m))
+      end.compact
+      class_ranges + instance_ranges
+    end
+  end
+end

data/lib/internal_api/rewriter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module InternalApi
+  # This uses the built-in Ruby callbacks for when new methods are defined:
+  # https://github.com/ruby/ruby/blob/c3cf1ef9bbacac6ae5abc99046db173e258dc7ca/object.c#L940-L954
+  module Rewriter
+    extend self
+
+    # rubocop:disable Metrics/MethodLength
+    SKIP_PATTERN = /(^_internal_api)|(^(singleton_)?method_added$)/.freeze
+    def add_instance_rewrite_hooks!(protectee, protector)
+      protectee.class_eval do
+        define_method(:method_added) do |method_name|
+          return unless InternalApi::Rewriter.should_overwrite?(
+            method_name,
+            instance_methods,
+            public_instance_methods
+          )
+
+          InternalApi.debug "#{self}##{method_name} protected by #{protector}"
+          InternalApi.rewrite_method!(self, method_name, protector)
+        end
+      end
+    end
+
+    def add_singleton_rewrite_hooks!(protectee, protector)
+      protectee.class_eval do
+        define_method(:singleton_method_added) do |method_name|
+          return unless InternalApi::Rewriter.should_overwrite?(
+            method_name,
+            methods,
+            public_methods
+          )
+
+          eigen = (class << self; self; end)
+          InternalApi.debug "#{eigen}.#{method_name} protected by #{protector}"
+          InternalApi.rewrite_method!(eigen, method_name, protector)
+        end
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    def should_overwrite?(method_name, methods, public_methods)
+      # Don't interfere with the metaprogramming
+      return false if method_name.to_s =~ SKIP_PATTERN
+      # And definitely don't try to do this twice
+      return false if methods.include?("_internal_api_#{method_name}".to_sym)
+
+      public_methods.include?(method_name)
+    end
+  end
+end

data/lib/internal_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module InternalApi
+  VERSION = File.read(File.join(__dir__, '..', '..', 'VERSION'))
+end

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: internal_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jack Danger
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-05-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: method_source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Create code boundaries within your Rails monolith
+email:
+- github@jackcanty.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- bin/setup
+- internal_api.gemspec
+- lib/internal_api.rb
+- lib/internal_api/full_method_source_location.rb
+- lib/internal_api/rewriter.rb
+- lib/internal_api/version.rb
+homepage: https://github.com/JackDanger/ruby_internal_api
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Carve up your Rails monolith via internal APIs
+test_files: []