Guillaume's Horrible Code-Along Blog

#guillaume-rant-palace

Fri, 27 Dec 2024 19:17:00 +0400

I logged into Twitter today. I wanted to download the archive of my data. In doing so, I couldn’t help but be taken back to the days when I was an active user, from Jan 2011 to October 2022.

I didn’t tweet much, but over the years, I had come to use Twitter as an outlet for my frustrations, cynicism, takes about working in–or generally interacting with–tech. Where this blog was the long-form, Twitter was the short. Looking at the archive, I remembered the moments. Some takes aged better than others, some were learning opportunities, and some landed flat.

I found that turning this frustration into a joke, involving people, and having them laugh with me was a good release valve. Sharing these takes with strangers on the internet was a good way to be told when I was wrong, and needed to reevaluate my priors.

There, I could only post about topics that were relevant to the public, but much of my takes were about the code and development practices of my employer, and I couldn’t share those publicly.

#guillaume-rant-palace

Around 2018, I needed to vent about something private to my employer, and thus couldn’t use Twitter. I decided to create a new Slack channel, #guillaume-rant-palace (Slack’s channel length limit wouldn’t allow the possessive 's'), and post there. I then pretty much made it a habit; whenever something deserved to be shared or discussed, or whenever I needed to vent, I’d write it there. If not for anyone else, at least for me.

I have no idea how it happened, but it took less than a week for someone to join, then our numbers grew slowly but steadily. Much like Twitter, I really enjoyed having this group of people to vent with, but also keep each-other honest, and learn together. It was at times cathartic, funny, salty, insightful. It gave us a place to scream into the void yet be heard. It gave us receptive colleagues with whom we could challenge established patterns.

I like to think that for one hot minute we formed a community that influenced ever so slightly the way the entire company thought about software. I like to believe it wasn’t groupthink. The channel has long disappeared, and I can’t download that archive; it’s impossible to verify.

We’ve now reached a size (or bureaucracy) where channel creation is restricted, and I certainly couldn’t recreate the conversations that went on in the #guillaume-rant-palace channel. Much like Twitter, I really miss it.

Ironically, this post is about the loss of both Twitter and #guillaume-rant-palace as avenues for this very blog post.

GraphQL ❤️ Sorbet and Unit Tests

Thu, 05 Nov 2020 14:00:00 +0400

For the past year, my team has been working on a project that exposes a GraphQL API, and, since we’ve been doing things quite differently than the rest of the company, I figured some of our ideas might be worth sharing. We’ve been using the graphql-ruby gem, and even though it doesn’t lend itself well to unit testing, we’ve insisted on writing unit tests. What’s more, we’ve also used Sorbet to prevent other categories of errors; in fact, most of our code is using typed: strict! In this post, I’ll share why we went out of our way to do this, and how it can be done.

If you don’t like boilerplate code, beware, the quantity of boilerplate required is staggering!

Note: for the purpose of this post, I will assume that you are familiar with the Sorbet and GraphQL syntaxes.

Primer

I want to start by explaining some of the challenges we had in designing our GraphQL API. The project we’re working on is an integration point for many other teams and projects of different domains, most of which we don’t control. However, these domains need inputs from the API, and they need to expose data of their own. As a result, my team can’t be expected to know everything going on in the other domains, just as it’s unrealistic to expect other teams to freeze their code.

Implementations will change. Methods will be added and removed. Classes will be renamed. Refactors will happen. For our project to be successful, we need to give developers (both internal and external to the project) the agency to make changes, and the confidence they are not compromising the stability of the API.

API

Simplistically, the goal of the API is to:

accept inputs from the client
map inputs to domain objects
invoke a procedure with the domain objects as inputs, and receive a domain object as outputs
map the returned domain object into an API output value
return the output value to the client

Our goal was to provide a high level of confidence that each of these steps works as expected, at the lowest cost possible in terms of dev time and feedback time.

Why Unit Tests

The graphql-ruby section on tests suggests relying on unit testing the domain, and integration testing the API. Integration testing is great, but it isn’t enough to check that domain types map correctly to API types, that API input types map correctly to domain types, or that the correct procedures will be invoked. Our API contains many, many types, and building tests that cover the cardinality of all possible type mapping would make for a very slow test suite. Unit tests don’t suffer from this problem, especially when paired with static analysis.

Unit tests allow us to check that all tested values will be mapped as expected.

Why Static Typing

I like to think of values used in APIs as a pyramid, in which the domain must be able to support all input values, and the output must support all the domain values.

For example, our API could use these types, where all types are identical:

Input = Integer
Domain = Integer
Output = Integer

It’s also possible to use an actual pyramid of types:

Input = Integer
Domain = Integer | Float
Output = Numeric

However, using types that can’t naturally represent the values they must support will require constraining. For example, if we used the following types, the API would require another way to constrain the values, often resorting to errors:

Input = Float
Domain = Integer
Output = PositiveInteger

In GraphQL and Ruby, constraining is quickly required, because GraphQL’s Int type is limited to 32 bits, whereas Ruby’s Integer type is not.

In practice, it will not always apply, but starting with that mindset will help us understand how our types are constrained.

Static analysis allows us to verify that each layer can support the values representable by the layers above it. This has been especially useful to catch changes in the domain that can’t be mapped by the API, because the tests don’t necessarily exist. For example, this change:

  Input = Integer
- Domain = Integer
+ Domain = Integer | Float
  Output = Integer

We haven’t been able to write tests of our API that would catch this change and alert us that Output’s type must also be changed. Static analysis catches this easily.

Practical Example

For the rest of this article, we’ll be working on a small API. Suppose there’s another team that owns the entirety of Messages, and yet we still need to allow interacting with Message objects in our API.

The domain is simple enough: we can create new messages using Domain::Message.create with an instantiated Domain::Message, and we will get back a Message object. The code below is the entire public API they expose.

# typed: strict

class Domain::Message
  extend(T::Sig)

  sig do
    params(message: Domain::Message)
      .returns(Domain::Message)
  end
  def self.create(message)
    # omitted
  end

  # Messages will be anonymous if from_name == nil
  sig do
    params(content: String, from_name: T.nilable(String))
      .void
  end
  def initialize(content:, from_name:)
    @content = content
    @from_name = from_name
  end

  sig { returns(String) }
  attr_reader(:content)

  sig { returns(T.nilable(String)) }
  attr_reader(:from_name)
end

Note: The code contained in this post has been made available in a separate repository on GitHub, and each commit corresponds to progress in this post.

Since we don’t know anything about Messages and we’re short on time, we’ll just expose an API that is a direct translation what’s offered internally. This is what the GraphQL definitions would look like, before we start implementing resolvers.

# For this example, we'll be using mostly
# the `MutationRoot`, but the graphql-ruby
# gem requires a valid `QueryRoot`, so we'll
# provide it with a dummy one.
class Api::QueryRoot < GraphQL::Schema::Object
  field(:version, Integer, null: false)
end

class Api::Message < GraphQL::Schema::Object
  extend(T::Sig) # sigs will be added later

  field(:content, String, null: false)
  field(:from_name, String, null: true)
end

class Api::MessageInput < GraphQL::Schema::InputObject
  extend(T::Sig)

  argument(:content, String, required: true)
  argument(:from_name, String, required: false)
end

class Api::MutationRoot < GraphQL::Schema::Object
  extend(T::Sig)

  field(:message_create, Api::Message, null: false) do |f|
    f.argument(:message_input, Api::MessageInput, required: true)
  end
end

This will generate the following GraphQL IDL:

schema {
  query: QueryRoot
  mutation: MutationRoot
}

type Message {
  content: String!
  fromName: String
}

input MessageInput {
  content: String!
  fromName: String
}

type MutationRoot {
  messageCreate(messageInput: MessageInput!): Message!
}

type QueryRoot {
  version: Int!
}

Testing Inputs

Input types need to be mapped to domain types, and we would very much like to test that they can be mapped correctly. The graphql-ruby gem allows the definition of a prepare method that does this mapping. Unfortunately, for Sorbet’s benefits, we’ll also need to define the fields as private methods. The upside is that we’ll also benefit from runtime type checking (albeit incomplete) in addition to static analysis.

class Api::MessageInput < GraphQL::Schema::InputObject
  # snip

  sig { returns(Domain::Message) }
  def prepare
    Domain::Message.new(
      content: content,
      from_name: from_name,
    )
  end

  private

  sig { returns(String) }
  def content
    self[:content]
  end

  sig { returns(T.nilable(String)) }
  def from_name
    self[:from_name]
  end
end

Unfortunately, adding tests to Api::MessageInput#prepare requires a bit of boilerplate to instantiate the objects. We can nonetheless test that all inputs will be mapped correctly.

RSpec.describe("Api::MessageInput") do
  describe("#prepare") do
    it("can map to a Domain::Message when all values are present") do
      input =
        Api::MessageInput.new(
          nil,
          ruby_kwargs: {
            content: "Hello Joe",
            from_name: "Guillaume",
          },
          context: nil,
          defaults_used: Set.new,
        )

      message = input.prepare

      expect(message).to(be_kind_of(Domain::Message))
      expect(message.content).to(eq("Hello Joe"))
      expect(message.from_name).to(eq("Guillaume"))
    end

    it("can map to a Domain::Message with a nil from_name") do
      input =
        Api::MessageInput.new(
          nil,
          ruby_kwargs: {
            content: "Hello Joe",
            from_name: nil,
          },
          context: nil,
          defaults_used: Set.new,
        )

      message = input.prepare

      expect(message).to(be_kind_of(Domain::Message))
      expect(message.content).to(eq("Hello Joe"))
      expect(message.from_name).to(be_nil)
    end
  end
end

Running tests show that this works as expected.

$ rspec

Api::MessageInput
  #prepare
    can map to a Domain::Message when all values are present
    can map to a Domain::Message with a nil from_name

2 examples, 0 failures

Testing Return Values

Testing return values will require a lot more boilerplate than for inputs.

The graphql-ruby gem instantiates GraphQL::Schema::Object values for every object passing through it, which has the benefit of being convenient if you’re abiding to all its recommendations, but wasteful if you aren’t. Spoiler: we aren’t. Instead we’d rather define functions that map from the domain objects into API objects, making them easier to test.

To do that, we’ll delegate one method per field to a singleton object. In our project we chose to have a Resolvers module per GraphQL class, with one singleton method per field.

Pure delegation isn’t going to work either, as we need to pass the underlying domain object. Luckily, Ruby has refinements which allow adding a delegate_to method that will not be exposed externally.

Note: In our project we’ve also found that we needed to pass the context in some situations, mainly for dependency injection. context will not be needed in this example, but I’m going to include it nonetheless, in case someone is tempted to try this approach on their own project. Our implementation is much longer and contains many verifications to remove affordances: the field must exist, the method must exist on the delegate, its arity must be correct, etc. I can provide a more thorough implementation if there’s interest.

# typed: false

# Unfortunately, Sorbet doesn't understand
# refinements for the moment, so this file
# has to be untyped. We'll also need to
# define a shim for `GraphQL::Schema::Object`,
# defining `delegate_to`.
module Api::GraphQLDelegation
  refine(GraphQL::Schema::Object.singleton_class) do
    def delegate_to(delegate, methods:)
      methods.each do |method_name|
        delegate_method = delegate.method(method_name)

        define_method(method_name) do |**args|
          if args.empty?
            delegate_method.call(object, context)
          else
            delegate_method.call(object, context, **args)
          end
        end
      end
    end
  end
end

Our implementation of the Resolvers module defines a lot of boilerplate, and I wish this pattern was supported directly in the graphql-ruby gem: using delegates instead of instantiating unnecessary objects would put less pressure on the garbage collector.

class Api::Message < GraphQL::Schema::Object
  using(Api::GraphQLDelegation)

  # fields omitted

  # The Resolvers module defines one strongly
  # typed functions for all `fields`.
  module Resolvers
    class << self
      extend(T::Sig)

      sig do
        params(object: Domain::Message, _: BasicObject)
          .returns(String)
      end
      def content(object, _)
        object.content
      end

      sig do
        params(object: Domain::Message, _: BasicObject)
          .returns(T.nilable(String))
      end
      def from_name(object, _)
        object.from_name
      end
    end
  end

  delegate_to(Resolvers, methods: [:content, :from_name])
end

The Sorbet annotations in this code are enough for Sorbet to notify us if we ever use a method that doesn’t exist (or no longer exists!), or if the types don’t line up like we expect them to.

This code also makes it easy to test that the Resolvers module can map from a domain type to types that GraphQL can represent.

RSpec.describe("Api::Message") do
  describe("#from_name") do
    it("returns the message author's name") do
      message =
        Domain::Message.new(
          content: "Hello Joe",
          from_name: "Guillaume",
        )

      expect(Api::Message::Resolvers.from_name(message))
        .to(eq("Guillaume"))
    end

    it("can be nil") do
      message =
        Domain::Message.new(
          content: "Hello Joe",
          from_name: nil,
        )

      expect(Api::Message::Resolvers.from_name(message))
        .to(be_nil)
    end
  end

  describe("#content") do
    it("returns the message's content") do
      message =
        Domain::Message.new(
          content: "Hello Joe",
          from_name: "Guillaume",
        )

      expect(Api::Message::Resolvers.content(message))
        .to(eq("Hello Joe"))
    end
  end
end

And run it!

$ rspec

Api::MessageInput
  #prepare
    can map to a Domain::Message when all values are present
    can map to a Domain::Message with a nil from_name

Api::Message
  #from_name
    returns the message author's name
    can be nil
  #content
    returns the message's content

Finished in 0.00612 seconds (files took 0.33929 seconds to load)
5 examples, 0 failures

We chose not to test the actual Api::Message object (since it performs no work). Instead, we have another, separate test that makes sure all boilerplate and wiring is done correctly. This test will be out of the scope of this post, however. While it isn’t exactly fast, it covers the entire schema in roughly 500ms, which is faster than the average integration test in our codebase.

We will implement and test the MutationRoot in the same way. There are two differences here, however. First, the object delegated by the MutationRoot has no semantic value, so we’ll just treat it as a BasicObject. Second, the graphql-ruby gem passes the field arguments as named parameters, so we’ll need to define them explicitly. Finally, we’ll define _context explicitly, only because using a splat (*) could cause confusion with named arguments.

class Api::MutationRoot < GraphQL::Schema::Object
  using(Api::GraphQLDelegation)

  # fields omitted

  module Resolvers
    class << self
      extend(T::Sig)

      sig do
        params(
          _obj: BasicObject,
          _context: BasicObject,
          message_input: Domain::Message,
        ).returns(Domain::Message)
      end
      def message_create(_obj, _context, message_input:)
        Domain::Message.create(message_input)
      end
    end
  end

  delegate_to(Resolvers, methods: [:message_create])
end

Similarly to Api::Message, we can write unit tests for the Api::MutationRoot.

RSpec.describe("Api::MutationRoot") do
  describe("#message_create") do
    it("calls Domain::Message with the message") do
      message =
        Domain::Message.new(
          content: "Hello Joe",
          from_name: "Guillaume",
        )

      expect(Domain::Message)
        .to(receive(:create).with(message).and_return(message))

      Api::MutationRoot::Resolvers
        .message_create(nil, nil, message_input: message)
    end
  end
end

Note: If you’d rather not use expect, you can use the context object to allow dependency injection. We do this extensively and it works well.

$ rspec

Api::MutationRoot
  #message_create
    calls Domain::Message with the message

Finished in 0.0111 seconds (files took 0.34917 seconds to load)
1 examples, 0 failures

While we’re at it, let’s see what Sorbet has to say.

$ srb tc
No errors! Great job.

Sweet! However, this isn’t very surprising, since we haven’t told Sorbet about the links between the API classes. For example, it would be possible for Api::MessageInput#prepare to return a value that’s incompatible with message_create.

 class Api::MessageInput < GraphQL::Schema::InputObject
   # snip

-  sig { returns(Domain::Message) }
+  sig { returns(Integer)) }
   def prepare
-    Domain::Message.new(
-      content: content,
-      from_name: from_name,
-    )
+    1
   end
 end

Sorbet isn’t able to tell us that this produces an invalid value.

$ srb tc
No errors! Great job.

Luckily, our test suite would catch this error, but it would be even better if Sorbet could tell us. Let’s do just that.

Adding Types

The problem we currently have is that Sorbet doesn’t understand the coupling that exists between the different pieces of the domain and API. Adding those will require even more boilerplate, but it’s achievable, and, in my opinion, definitely worth it.

Here’s how we managed to do it:

Input types define a PrepareType type alias, which is the return type of the prepare method.
Output types define an ObjectType type alias, which is the type of the object value they receive.
All inputs and outputs can be either PrepareType or ObjectType, or primitive types which GraphQL understands.

On Api::MessageInput, we will define a PrepareType type alias, and use it (rule #1).

 class Api::MessageInput < GraphQL::Schema::InputObject
   # snip

+  PrepareType = T.type_alias { Domain::Message }

-  sig { returns(Domain::Message) }
+  sig { returns(PrepareType) }
   def prepare
     Domain::Message.new(
       content: content,
       from_name: from_name,
     )
   end
 end

On Api::Message, define an ObjectType and use it (rule #2).

 class Api::Message < GraphQL::Schema::Object
   using(Api::GraphQLDelegation)

   # fields omitted

+  ObjectType = T.type_alias { Domain::Message }

   module Resolvers
     class << self
       extend(T::Sig)

       sig do
-        params(object: Domain::Message, _: BasicObject)
+        params(object: ObjectType, _: BasicObject)
           .returns(String)
       end
       def content(object, *_)
         object.content
       end

       sig do
-        params(object: Domain::Message, _: BasicObject)
+        params(object: ObjectType, _: BasicObject)
           .returns(T.nilable(String))
       end
       def from_name(object, *_)
         object.from_name
       end
     end
   end

   delegate_to(Resolvers, methods: [:content, :from_name])
 end

Finally, on Api::MutationRoot, we’ll use the type aliases (rule #3).

 class Api::MutationRoot < GraphQL::Schema::Object
   using(Api::GraphQLDelegation)

   # fields omitted

   module Resolvers
     class << self
       extend(T::Sig)

       sig do
         params(
           _obj: BasicObject,
           _context: BasicObject,
-          message_input: Domain::Message,
+          message_input: Api::MessageInput::PrepareType,
-        ).returns(Domain::Message)
+        ).returns(Api::Message::ObjectType)
       end
       def message_create(_obj, _context, message_input:)
         Domain::Message.create(message_input)
       end
     end
   end

   delegate_to(Resolvers, methods: [:message_create])
 end

With those changes, our types are properly coupled together, and applying the same erroneous changes as before (prepare returning Integer) will produce errors:

$ srb tc

sorbet.rb:236: Expected Domain::Message but found Integer for argument message https://srb.help/7002
     236 |        Domain::Message.create(message_input)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    sorbet.rb:16: Method Domain::Message.create has specified message as Domain::Message
    16 |    params(message: Domain::Message)
                   ^^^^^^^
  Got Integer originating from:
    sorbet.rb:235:
     235 |      def message_create(_obj, _context, message_input:)
                                                   ^^^^^^^^^^^^^^
Errors: 1

Success!

Now let’s be real for a second. Our tests had also caught this problem, and the code required for static analysis added a TON of boilerplate, and you may be wondering: is it really worth it? If you’re used to having static typing or swear by unit testing, you may have already answered “yes”, but it’s entirely normal to remain skeptical. In the next section, we’ll see why I consider all this boilerplate worthwhile, and which situations make it useful.

Changing Things

Recall that the Domain::Message is owned by another team. They will not necessarily tell us when they make changes, in part because they may not know that we’re using their APIs. The boilerplate written in the previous section was an attempt to force them into knowing by coupling our API to theirs.

When we design software, we try to avoid breaking changes, but from what I’ve seen, they’re almost inevitable.

In this section, we’ll see how 2 types of breaking changes can be caught by Sorbet that would not have been caught by tests: when an input type becomes narrower (accepts less values) than it was before, or when an output type becomes wider (contains more values).

Input Narrowing

In some cases, it may make sense to narrow the inputs of a method. For example, maybe anonymous messages have been removed from the scope, and the team wants to narrow the input type of fromName to just String.

 class Domain::Message
   extend(T::Sig)

   # snip

   sig do
-    params(content: String, from_name: T.nilable(String))
+    params(content: String, from_name: String)
       .void
   end
   def initialize(content:, from_name:)
     @content = content
     @from_name = from_name
   end

   # snip

-  sig { returns(T.nilable(String)) }
+  sig { returns(String) }
   attr_reader(:from_name)
 end

It’s entirely possible that, writing integration tests only, we wouldn’t have written a test for fromName = nil. Luckily, we wrote unit tests, so this change wouldn’t go unnoticed, and it would signal to the domain team that they need to communicate with our team about these changes.

$ rspec

Api::MessageInput
  #prepare
    can map to a Domain::Message when all values are present
    can map to a Domain::Message with a nil from_name (FAILED - 1)

Api::Message
  #from_name
    returns the message author's name
    can be nil (FAILED - 2)
  #content
    returns the message's content

Api::MutationRoot
  #message_create
    calls Domain::Message with the message

Finished in 0.01886 seconds (files took 0.33419 seconds to load)
6 examples, 2 failures

Even in the event that we had omitted to write any test, Sorbet would still catch the problem.

sorbet.rb:92: Expected String but found T.nilable(String) for argument from_name https://srb.help/7002
    92 |      content: content,
    93 |      from_name: from_name,
    sorbet.rb:25: Method Domain::Message#initialize has specified from_name as String
    25 |    params(content: String, from_name: String)
                                    ^^^^^^^^^
  Got T.nilable(String) originating from:
    sorbet.rb:92:
    92 |      content: content,
    93 |      from_name: from_name,
Errors: 1

Output Widening

Sometimes, the type of the return value will need to be widened, to accomodate for changes. It’s next to impossible to design tests that will preempt errors stemming from this kind of changes, but static analysis will find them without a problem.

For example, imagine that, in certain scenarios, Domain::Message.create will not be able to return a Domain::Message. This could happen if the datastore is overwhelmed, for example. The domain team choses to instead buffer the write, and return a Domain::Pending value, indicating that the write will happen at a later time.

 class Domain::Message
   extend(T::Sig)

+  class Pending; end
+
+  # Buffer will be a class variable
+  # just so we can make a working example
+  @buffer = T.let([], T::Array[Domain::Message])
+
   sig do
     params(message: Domain::Message)
-      .returns(Domain::Message)
+      .returns(T.any(Domain::Message, Pending))
   end
   def self.create(message)
-    # omitted
-    message
+    if overwhelmed?
+      @buffer.push(message)
+      Pending.new
+    else
+      # omitted
+      message
+    end
   end

+   sig { returns(T::Boolean) }
+   def self.overwhelmed?
+     false
+   end

   # snip
 end

Once again, Sorbet will find the problem and tell us that the return value of Domain::Message.create is incompatible with Api::MutationRoot#message_create.

$ srb tc

sorbet.rb:143: Returning value that does not conform to method result type https://srb.help/7005
     143 |        Domain::Message.create(message_input)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Expected Domain::Message
    sorbet.rb:142: Method message_create has return type Domain::Message
     142 |      def message_create(_obj, _context, message_input:)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Got T.any(Domain::Message, Domain::Message::Pending) originating from:
    sorbet.rb:143:
     143 |        Domain::Message.create(message_input)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Errors: 1

How to handle this kind of change will ultimately be the author’s decision, but I wanted to briefly touch on union type in graphql-ruby and how to handle them in Sorbet.

For our example we want to expose the Pending message creation in the GraphQL API, and so we need to introduce a Api::MessagePending type to represent it.

class Api::MessagePending < GraphQL::Schema::Object
  using(Api::GraphQLDelegation)

  field(:_singleton_value, :bool, null: false)

  ObjectType = T.type_alias { Domain::Pending }

  module Resolvers
    class << self
      extend(T::Sig)

      sig do
        params(object: ObjectType, _: BasicObject)
          .returns(T::Boolean)
      end
      def _singleton_value(object, *_)
        true
      end
    end
  end

  delegate_to(Resolvers, methods: [:_singleton_value])
end

We also need to change the return value of messageCreate to be a union of Pending and Message, which we can call MessageCreateResult. Luckily, the union types in graphql-ruby make it easy to add Sorbet, so we won’t need to rely on the Resolvers module like before. We just need to make sure that its ObjectType is the union of all ObjectType of its possible_values. In the resolve_type method, we can even make use of Sorbet’s exhaustiveness checking with T.absurd.

Our resolve_type will return a tuple of two values. The first value of the tuple is the GraphQL class that contains the mapping functions. The second values allows unwrapping the value. This isn’t super useful in the current code, but if we were using wrapper objects (like a Result type), it would simplify the code a lot, since members of the union wouldn’t need to share one type.

class Api::MessageCreateResult < GraphQL::Schema::Union
  extend(T::Sig)

  possible_types(Api::Message, Api::MessagePending)

  ObjectType =
    T.type_alias do
      T.any(Api::Message::ObjectType, Api::MessagePending::ObjectType)
    end

  sig do
    params(object: ObjectType, _: BasicObject)
      .returns(T.any(
        [T.class_of(Api::Message), Api::Message::ObjectType],
        [T.class_of(Api::MessagePending), Api::MessagePending::ObjectType],
      ))
  end
  def self.resolve_type(object, *_)
    case object
    when Domain::Message
      [Api::Message, object]
    when Domain::Message::Pending
      [Api::MessagePending, object]
    else
      T.absurd(object)
    end
  end
end

 class Api::MutationRoot < GraphQL::Schema::Object
   using(Api::GraphQLDelegation)

   # fields omitted

   module Resolvers
     class << self
       extend(T::Sig)

       sig do
         params(
           _obj: BasicObject,
           _context: BasicObject,
-        ).returns(Api::Message::ObjectType)
+        ).returns(Api::MessageCreateResult::ObjectType)
       end
       def message_create(_obj, _context, message_input:)
         Domain::Message.create(message_input)
       end
     end
   end

   delegate_to(Resolvers, methods: [:message_create])
 end

Sorbet will understand this correctly, and notify us if the return type of Domain::Message.create is once again changed.

$ srb tc
No errors! Great job.

Conclusion

In this post, we’ve seen a few ways in which we can define GraphQL schemas in Ruby, unit test them, and add Sorbet static analysis. We’ve seen a few ways in which unit tests and Sorbet would be able to catch breaking changes, which would be next to impossible to catch using integration tests only.

I hope that you’ll now consider annotating your GraphQL schema with Sorbet and benefit from its much faster feedback loop, as well as its ability to reveal bugs that are impossible to find only with tests.

Finally, if you are or you know a contributor of graphql-ruby, can you add the possibility to delegate fields to an object and skip the instantiation of GraphQL::Schema::Object, pretty please!

Type Variance Explained To a Ruby Developer

Sun, 21 Jun 2020 20:00:00 +0400

A few months ago, I found myself trying to explain type variance to a coworker whose experience is mainly Ruby. Dynamically typed languages such as Ruby don’t ask the developers to specify the type variance. I found that while they develop an instinct of what usages are acceptable and which aren’t, these developers don’t codify it in the same way developers in statically typed languages do. In trying to explain, I had great difficulty driving home the difference between covariance and contravariance. Their good instinct made it hard for me to fill the gap in their understanding. After a while, I remembered the way Simon Génier first explained it to me, and that way was a success.

This post is how I would explain type variance to a Ruby developer, without throwing the entire Computer Science manual at them. Throughout the post, we will suppose a typical Animal type hierarchy, with Dog and Cat as subtypes.

class Animal
  def age
    @age
  end
end

class Cat
  def purr
    puts "Purr"
  end
end

class Dog
  def fetch(ball)
    puts "Fetching the ball"
  end
end

Type Variance

In computer programming, we can divide types into simple types (ex: Integer, String, Symbol), and types composed of other members (ex: Array, Hash, Enumerable). This composition is often called parameterization. An Array<Integer> (an Array of Integer) said to be parameterized by the Integer type.

Type variance allows us to describe the relationship between the composed type and its members. Intuitively, we know that Enumerable<Cat> is a subtype of Enumerable<Animal>, but it’s harder to understand that Logger<Animal> is a subtype of Logger<Cat>. I’ll explain why that’s the case, but first, let’s talk about Arrays.

The Curious Case of Arrays

In dynamically typed languages as well as in languages that added generics after-the-fact, Arrays are weird.

Let’s examine a print_age method takes an Array of Animals and prints their age.

# @params animals Array<Animal>
def print_age(animals)
  animals.each { |a| puts(a.age) }
end

The print_age method can be called an array containing any animal:

# Array<Dog>
dog_array = [Dog.new, Dog.new]
print_age(dog_array)

# Array<Cat>
cat_array = [Cat.new, Cat.new]
print_age(cat_array)

# Array<Animal>
animal_array = [Dog.new, Cat.new]
print_age(animal_array)

We can also have another method named adopt that adds animals to the list:

# @params into_animals Array<Animal>
def adopt(into_animals)
  into_animals.push(Dog.new)
end

Now can you adopt in the same arrays? Let’s see.

# Array<Animal>
animal_array = [Dog.new, Cat.new]
adopt(animal_array)
# animal_array is still an `Array<Animal>`, no problem

# Array<Cat>
cat_array = [Cat.new, Cat.new]
adopt(cat_array)
# OH NO!!! [Cat, Cat, Dog]. This is no longer an `Array<Cat>`

The answer is no: adopt cannot use the same arrays as print_age. However, the adopt has a property that print_age did not have, it accepts Array<Object>.

# Array<Object>
object_array = [Dog.new, Object.new]
adopt(object_array)
# This is fine too! [Dog, Object] is a valid `Array<Object>`.

We can also notice that we cannot send object_array into print_age, because Object doesn’t define the age method.

What can we learn from this? Depending if you read from the array or write to it, the type doesn’t behave the same.

Sources Are Covariant

Composed types from which you can exclusively read or take stuff are called sources. Examples include Enumerable and Reader. These become more specific as their type members become more specific. As a result of Dog being a subtype of Animal, Enumerable<Dog> is a subtype of Enumerable<Animal>; you can pass an Enumerable<Dog> to any method that expects an Enumerable<Animal>.

Sinks Are Contravariant

Sinks are the opposite of sources: they’re types to which you can exclusively write or put stuff in. Examples include Logger or Writer. Perhaps counter-intuitively, these become more specific as their type member become less specific! That means that Logger<Animal> is in fact a subtype of Logger<Dog> (because Logger<Animal> will be able to log for any Dog as well.

Read and Write, Put and Take

What if a method needs to do both? Read and write, put and take? It would appear that they are at the intersection of covariance and contravariance… and that’s exactly right: they’re invariant. No subtyping is possible.

In an ideal world, Array<Dog> is neither a subtype nor a supertype of Array<Animal>. In practice, even if Array, HashMap and other read/write containers should be invariant, many languages will consider them covariant because of historic reasons.

Conclusion

Hopefully this piece will help you understand type variance better, or explain it to a curious coworker.

Affordance for Errors, part 3

Tue, 18 Feb 2020 23:00:00 +0400

In the first post of this series, I showed how a few APIs afford errors to their users. In the second post, I showed a few examples of how other APIs or languages have avoided or solved the same problems. In this third and final post, we will work through an example of designing an API.

When I design APIs, I try to think of all the ways it could possibly be misused, and remove as many ways as possible. Sometimes, this comes at the cost of some ergonomy, but how much I’m willing to sacrifice depends on a few factors: the criticality of the errors, the impact on ergonomy, the (handwavy) likelihood that it will occur, to name a few.

Design Example: Reservation Manager

I was recently writing an API to our reservation manager (the system holds reservation for carts, and disallows selling more items than are available). From the outside, the functionality is simple. You can reserve the items of a cart. Once reserved, the reservation can be claimed (ex: after the payment is successful) or unreserved (ex: if the payment failed).

Who Are The Users?

I think the very first step of API design is empathy. Yearn for your users to succeed in their task. Understand where they’re coming from. Make sure your APIs can be composed with the other tools they use.

The most important question you must ask yourself: “who will the users be?”. Are they interns, senior developers, or principal engineers? Will they use your API every day, once per quarter, or once per decade? Is your API the cornerstone of their feature, or are they using it as an afterthought?

Whenever possible, aim for the lowest common denominator. If an intern unfamiliar with the language using this API for the first time can succeed, the probability that a principal engineer using it for the 10th time will too is very high. When it’s less practical, understanding your users will help you make the right tradeoffs between the different factors.

In my case, this API is likely to be used by junior developers, and very rarely. They will definitely plan ahead as this will be integral to what they’re building.

Idiomatic API

I started by jotting down a first draft of the API, that handled all the cases necessary, in an idiomatic Ruby fashion. It looked something like this:

manager = ReservationManager.new
is_reserved = manager.reserve(cart)
if is_reserved
  if process_payments(cart)
    manager.claim(cart)
  else
    manager.unreserve(cart)
  end
else
  # handle error
end

However, as we’ve seen previously, this API affords a lot of errors.

Identifying Affordance for Errors

Using the learnings from the first post, we can quickly identify a few problems:

It’s possible to ignore the return value of reserve and treat all reservations like they succeeded.
Additionally to #1, they can call claim and unreserve without having reserved in the first place.
Is it legal to use different instances of ReservationManager for reserve and claim or unreserve?
It’s impossible to know when the reservation has exceeded its lifetime (ex, it has been garbage collected), and it’s impossible to force the user to consume (claim or unreserve) the reservation.

For example, if the user had wrong assumptions about their system, they could write this implementation:

manager.reserve(cart)
if process_payments(cart)
  manager.claim(cart)
end

Knowing that the users of this system will use this API approximately once in their entire career, I strongly favour reducing the surface for errors over idiomacy or ergonomy. Let’s see how we can solve this problem.

Removing the Affordances

To partially remove the affordance #1, we need to give an incentive to the user to use the return value. In fact, we will give them no choice. We can start by making reserve return a Reservation object, which is now the owner of claim and unreserve methods. In doing so, we also solved #3; our users cannot use a different instance of ReservationManager to claim or unreserve.

reservation = manager.reserve(cart)
if reservation.success?
  if process_payments(cart)
    reservation.claim
  else
    reservation.unreserve
  end
else
  # handle error
end

With this API, we only partially solved #1, and we haven’t solved #2 at all, however. One can still fail to check if the reservation was successful. To solve this, we can wrap our Reservation in a Result object (aka, a kind of Either monad), forcing the user to at least check for success.

The usage of the Result object could be surprising to some Ruby developers, but in our codebase they are very common, and they wouldn’t startle anyone.

result = manager.reserve(cart)
result
  .on_success do |reservation|
    if process_payments(cart)
      reservation.claim
    else
      reservation.unreserve
    end
  end
  .on_error do |error|
    # handle error
  end

Using this version, the users will have no choice but to consider whether the reservation was successful before they proceed further with it.

Depending on the various factors, we could decide to stop here; we’re already in a much better state than the original API. However for this API, I really wanted to make sure I solved #4 and force the user to claim or unreserve. We can do so by trading the return value of reserve for a mandatory block that will receive the reservation result.

manager.reserve(cart) do |result|
  result
    .on_success do |reservation|
      if process_payments(cart)
        reservation.claim
      end
    end
    .on_error do |error|
      # handle error
    end
end

This allows us to unreserve the reservation if it hasn’t been consumed by the end of the block. Depending on the specifics, we can also choose to raise if the reservation hasn’t been consumed, to notify the users that their code has a problem.

With this API in place, we have dramatically reduced the surface for error. The objects in play will naturally guide the our users towards the correct way to use our API, and even if they don’t, it won’t compromise the correctness of our system.

Opinions may vary, but in mine, we haven’t sacrificed ergonomics by the slightest to get here, either.

Conclusion

In the first post of this series, I showed a few ways in which common APIs allow their users to make mistakes. My goal was to help you take notice of the problem, so that you can find similar problems (and more) in your own APIs. In the second post, we saw how others have solved the same problems, to help you see ways to remove the affordance you give. In this final post, I went through an example, and explained how I design APIs, and how I try to make it easy for my users to make no error. I sincerely hope you can take something away from this series, and that you start taking notice of, and start removing, the affordance for errors in your APIs.

Affordance for Errors, part 2

Sun, 16 Feb 2020 15:00:00 +0400

In the first part of this series of three posts, I outlined a few common Ruby and Rails API, and explained the errors they afford their users. In this second post, I’ll discuss how other tools have avoided these problems, and how those solutions may apply to Ruby and Rails. I’ll be reusing the examples from the previous post. If you haven’t read it, I suggest you start there: Affordance for Errors, part 1.

How Others Have Solved Similar Problems

Jump right ahead:

ActiveRecord’s Errors API

Quick reminder: Some APIs force the user to invoke methods in a particular order. Ex: ActiveRecord forces you to use the valid? method before calling the errors method (link).

user = User.new
user.errors.any?
# => false

user.valid?
# => false

user.errors.any?
# => true

An obvious way to remove this surface for error would be to generate errors when the method is called.

Another, perhaps more interesting way, is Ecto’s Changeset API. It completely eliminates the problem by using Changeset which are either valid or invalid, and are the vehicle for change. If it were Rails, you would perhaps write it this way:

changes = user.change(name: "Guillaume")
if changes.valid?
  user.save(changes)
end

N + 1

Quick reminder: Some APIs’s default usage mode is what users consider a mistake. Ex: ActiveRecord allows mistakenly loading records in a serial manner, rather than as a batch (link).

I can already hear Alex Snaps complaining about ORMs. ORMs have their fair share of issues, I get it! I guess this problem exposes a conundrum: either we allow the prevalent* N+1 issue, or we force coupling between unrelated pieces of code.

All the approaches to solving this problem I can think of consist of considering that loading an association of a record loaded through a has_many association without specifying how, is invalid. Let’s dissect that.

investor = Investor.find(id)

investor.accounts.each do |account|
  puts account.fund.name
end

In the previous code, accounts is a has_many association on investor, so any association of it cannot be loaded unless we specify how. This would prevent the account.fund from working. However, if an Account was loaded outside an association, it could still be considered valid, ex:

1
2
3

account = Account.find(id)

puts account.fund.name # this is fine

Rails already allows specifying how to load associations, with includes, eager_load, or preload, ex:

investor = Investor.includes(accounts: :fund).find(id)

investor.accounts.each do |account|
  puts account.fund.name
end

This is sufficient to prevent the problem. We could also imagine a different API achieving the same results:

investor = Investor.includes(accounts: :fund).find(id)

investor.accounts(preload: :fund).each do |account|
  puts account.fund.name
end

# or

investor.accounts.each do |account|
  puts account.load_fund.name
end

The point is to make situations that produce N+1 only achievable explicitly. This is the path Ecto chose.

* You don’t have to take my word for it Google “Rails performance tips and tricks”. Nearly all of them will mention N + 1 queries.

Illegal States

Quick reminder: if no illegal states can be represented, we never have to worry about the validity of our objects.

I don’t think I can express this better than Yaron Minksy, but I’ll try to bring it into the Ruby world, if only because this is my favourite topic.

`String`, `Hash`, and other primitives

More often than not, when we use the language’s primitives, we give up an opportunity to express the domain model of our application. When we use a String to represent an Email, we haven’t encoded the fact that it needs to satisfy some constraints (ex: have an @, or satisfy a regular expression, or have a finite length). When we use Hash to represent structured data, we allow the possibility that some keys will be unset, or that some other keys will have values. We can fix all these problems by using classes specific for our use-cases.

State Machines

Finding examples for illegal states in state machines is almost trivial. A good indicator is the presence of many nullable attributes. Let’s take for example a Transaction state machine, that models the exchange of money. Without proper modelling, it could have this shape (simplified, showing only the bare minimum):

class Transaction
  # The monetary value of the transaction
  attr_reader(:amount)
  # Can be `:pending`, `:success`, `:failed`
  attr_reader(:status)
  # Only present if the transaction has
  # failed, `nil` otherwise
  attr_reader(:failure_reason)
  # Time at which the Transaction became
  # `:success` or `:failed`, `nil` otherwise
  attr_reader(:completed_at)
end

We can see in this example that some states are illegal, for example if status is :success but failure_reason is present, or if status is pending, but completed_at is present.

We can instead express the same object in a way that does not allow these illegal states. We can introduce classes for each possible state, that have the methods valid only for those states. The Transaction class will contain only the methods that are transcendental to states.

class TransactionPending
  # Nothing perticular here
end

class TransactionSuccess
  attr_reader(:completed_at)
end

class TransactionFailure
  attr_reader(:completed_at)
  attr_reader(:failure_reason)
end

class Transaction
  attr_reader(:money)
  # One of `TransactionPending`, `TransactionSuccess`,
  # or `TransactionFailure`
  attr_reader(:state)
end

With this change, only valid states can be represented. It’s impossible to have a TransactionSuccess with a failure_reason, or a TransactionPending with a completed_at.

Incomplete Booleans

In Part 1, I also gave examples of “Incomplete Booleans” that can be combined to express illegal states. The example given was of two booleans: inventory_is_managed and allow_negative. The illegal states manifests itself when inventory_is_managed is false, because any value of allow_negative makes no sense. The problem is that there are 3 possible values, but the structure allows us to represent 4 values.

We already know many ways to express a finite-but-larger-than-two number of values. Some people will use Symbol, String, or Integer values to that effect, and validate that the value is part of a finite list.

1
2

# can also be :managed_lax or :unmanaged
product.inventory_policy = :managed_strict

The way I prefer structuring it is by using objects:

class InventoryPolicy
end

MANAGED_STRICT = InventoryPolicy.new
MANAGED_LAX = InventoryPolicy.new
UNMANAGED = InventoryPolicy.new

product.inventory_policy = MANAGED_STRICT

The first reason is that it makes type checking easier (is_a?(InventoryPolicy)). It also makes it possible to give behaviour to the different InventoryPolicy if the need arises, by adding methods to the objects. When that becomes the case, it will also be trivial to do dependency injection, for example by creating a test-only InventoryPolicy. In general, in the worst case, there is no difference between that and using symbols, and in the best case, it’s a much more extensible design.

Ruby’s Visibility Modifiers

Quick Reminder: Some APIs do not meet the user’s expectations. Ex: Ruby’s visibility modifiers (private, public, protected) have no effect when using def self.method_name.

That this specific problem is such a common error pains me the utmost, because it is so unnecessary. Approximately 100% of other languages do not have this problem, by having visibility modifiers at the method definition level. In fact, it even works in Ruby, and many large companies have adopted this style. It may be inelegant, but it removes this opportunity for errors altogether:

class Foo
  private def baz
    :baz
  end
end

My preferred way is the method of singleton class opening, because it’s symmetric with normal class definitions:

class Foo
  class << self
    def baz
      :baz
    end
  end
end

I don’t really want to dwell on this too much. The key lesson is: be empathetic towards your users, understand what they expect, and make sure your APIs match their expectations.

Ignored Values

Quick reminder: Some APIs return critical values that are easy to ignore. Ex: ActiveRecord’s save method returns false when a record could not be saved.

In Ruby, this affordance is very hard to remove without resorting to exceptions. For APIs where handling errors is critical, it can be enforced by requiring a lambda injection:

`1`	`user.save(on_error: -> (e) { ... })`

While I do believe that using exceptions for fatal cases is great, I personally dislike using exceptions for cases that should be handled by the user, for many reasons. I’m not sure I need to list them, and I don’t think I can do so exhaustively, but in case it’s helpful, here are a few reasons:

Exceptions add a second way methods can return, adding complexity.
Unlike in some other languages, in Ruby it’s impossible to know the entire set of exceptions a method can raise, making it very hard to know which exceptions should be expected, and of those, which should be handled.
More often than not, an exception raised will leave inconsistent state in the program, in stackframes that were not equipped to deal with it.

As a result, I generally prefer returning objects that explain the error that occurred, instead of using exceptions. This makes it important to make sure the returned values are not ignored.

Some languages have solved this problem in interesting ways; some have implemented type systems in which values of certain types cannot be produced if they are not consumed. See substructural type systems on Wiki.

In Rust specifically, API developers can mark return values as must_use, meaning that the return value must be consumed (or checked). Failing to do so would result in a compiler warning. ATS achieves similar results via a concept of “proofs” where unconsumed proofs prevent compilation.

In languages where destructors are controlled, it would be possible to panic if the return value has not been consumed.

In Ruby, you could technically do it by using define_finalizer(obj) { raise } and undefine_finalizer(obj) :trollface:.

Missing Coupling

Quick reminder: Some APIs require things that go together, without expressing the coupling. Ex: Hash requires the methods hash and eql? to be coupled, without expressing it. Moreover, the Object class defines both methods, making it easy to define one without defining the other, leading to subtle bugs.

The ergonomics around this are hard to get right. One possibility would be to remove hash and eql? from all objects. This would be a large inconvenience, and I don’t think the added correctness would be worth it. Another would be to force reimplementing one method if the other is redefined. I think this second approach would be viable; we wouldn’t sacrifice much ergonomics, yet we’d largely prevent this type of error.

This, of course, is where interfaces (or traits) shine, by expliciting the coupling between all the required pieces an API needs.

Conclusion

In this post, we covered the various affordances given by common Ruby and Rails APIs, as well as common mistakes I’ve seen in codebases I worked on. We explored ways to spot them and avoid making them in designing our own APIs. I hope you learned something, or that this post helped you put words on ideas you already had, such that you can discuss them with the people on your teams, such that we can all build better APIs, with less affordance for errors. In Part 3, I will be going over how I approached and designed a specific API.

Affordance for Errors, part 1

Wed, 29 Jan 2020 23:00:00 +0400

A few years ago, I read Sandi Metz’s blog post about affordances and it stuck with me. I started minding how the APIs I write can be misused; I started noticing the surface I leave for the users of my APIs to make errors. Soon after I started noticing how the APIs we use every day are full of affordance for error.

In this first of three posts, I want to show a few examples of how common APIs (mostly in Ruby and Rails) can be accidentally misused. Maybe this will spark a discussion, or will incite people to share other issues they’ve seen. The second post will explore solutions to the problems from this post. In the final post of this series, I will show how I approach API design to minimize the affordance for errors while offering the best ergonomics I can.

Why Bother?

You may be wondering why this matters, why can’t just write better code, without mistake. After all, we’re smart people, we should be able to learn these tools and to not make mistakes… If you are the kind of developer that can write bug-free code, this blog post is even more so for you, as your coworkers cannot. Developers are humans. We get tired, we forget, our attention lapses, we’re juggling umpteen other things in our heads. For many reasons, we end up making mistakes. It is then our shared responsibility to make your APIs human-friendly.

Moreover, good APIs minimize the amount of mistakes we can make, they remove the pain and frustration of using them. They lower the cost of entry. They don’t require you to understand how things are implemented “on the metal”. Providing good APIs with minimal affordance for errors is about making the life of your fellow developers just a little better, making them just a little more productive, easing their cognitive load just a little.

Good APIs will naturally guide developers towards the best ways to use them, in the same subtle yet important way the bumps on the F and J keys guide your hands towards the good hand placement.

My hope is that after reading this post, you too will start taking notice of what errors you afford your users, and that we can all use this as a starting point to write better, human-friendlier APIs.

Examples of Surfaces for Errors

Jump right ahead:

ActiveRecord’s Errors API

I want to start this off with an easy, approachable example: ActiveRecord’s errors API, which requires a specific incantation.

class User < ApplicationRecord
  validates(:name, presence: true) # 1
end

user = User.new # 2
user.errors.any? # 3
# => false

user.valid? # 4
# => false

user.errors.any? # 5
# => true

For those unfamiliar with Rails, in the previous example, we

We create a User class which specifies that the name attribute must be set, otherwise it’s not valid (#1)
We then instantiate a User, without giving it a name (#2); we can then expect it to be invalid
However, we can see that it contains no errors (#3)
This is because ActiveRecord requires the programmer to use valid? (#4) before calling errors, which mutates the User to set errors (#5)

APIs like this can often be exposed in ways that completely suppress the problems, so much so that I’ve always been stricken that Rails kept choosing not to do anything (reminder: exploring solutions will be the topic of the second post).

N + 1

Some APIs, like ActiveRecord, allow mistakenly loading data serially instead of in a batch manner, without guiding the user towards the more performant approach.

investor = Investor.first

investor.accounts.each do |account|
  puts account.fund.name
end

# Fund Load (1.2ms)  SELECT  "funds".* FROM "funds" WHERE "funds"."id" = $1 LIMIT $2  [["id", 6], ["LIMIT", 1]]
# Fund Load (1.4ms)  SELECT  "funds".* FROM "funds" WHERE "funds"."id" = $1 LIMIT $2  [["id", 7], ["LIMIT", 1]]
# ... and so on for each account

Because the code that loaded the investor object did not preload the fund, every iteration of the loop will issue a query to load one fund.

If you have used Rails with ActiveRecord for more than a few days, the probability that you’ve encountered or written code with this mistake are high. This problem is so common that a gem (Bullet) was written to help developers detect when they cause it.

Illegal States

If I were to choose, this would be the most important one.

Make illegal states unrepresentable

Attributed to a 2011 post by Yaron Minksy (which I became aware of only much later), this quote completely changed the way I approach software design. This practice eliminates so many possible mistakes that it’s hard to even explain the implications.

If no illegal state can be represented, we never have to worry about the validity of objects.

More often than not, however, we write code that allows representing invalid state. ActiveRecord initialization is a good example, but there are so many others. All APIs that use Hashes to represent state immediately allow illegal state. There are many, many variations of APIs offering this kind of surface for errors, I encourage you to keep your eyes peeled and take notice.

Incomplete Booleans

One example, I’ve recently used an APIs for inventory management using a number of booleans to represent possible states, but the number of allowed states is less than the booleans combined values allow. Inventory items can be configured with the boolean values inventory_is_managed (the inventory counter can be set and is decremented after a sale), and allow_negative (the item can continue selling once after it the counter reached zero).

The problem is that this API has 4 configurations, but only 3 are valid:

(inventory_is_managed: true, allow_negative: true) the inventory is managed, but can go negative
(inventory_is_managed: true, allow_negative: false) the inventory is managed, and cannot go below zero
(inventory_is_managed: false, allow_negative: _) the inventory is not managed; whether or not it can go below zero is meaningless

Users of this API should not be able to set any value for allow_negative if inventory_is_managed is false.

Email is a String, Struct is a Hash

Ruby code is plagued with primitive obsessions. We represent emails using String, and “complex” data using Hash. Neither of these classes allow preserving the invariants of our system (ex: the email matches a regular expression). As a result, most codebases I’ve seen build defenses; they validate the state more than once.

Ruby’s Visibility Modifiers

There’s an entire category of errors stemming from APIs allowing you to do the wrong thing, while seemingly doing the right thing.

Visibility modifiers (private, protected, public) are prime examples; they are the source of many mistakes, by newcomers’s mismatched expectations and veterans’s lapse of attention. To say nothing of the fact that protected means something different than in other languages, many devs make mistakes when it comes to singleton methods, often called “class methods”. Here’s an example:

class Foo
  private

  def self.bar
    :bar
  end
end

Many devs would expect the Foo.bar method to be private to Foo–perhaps because many call it a class method–, however it is not. The reason is that private is a method on Foo, telling it to mark the methods defined after as private. It does not affect Foo’s singleton class. To learn more about the relation between classes and their singleton classes, refer to The Ruby Object Model.

That it is such a common error pains me the utmost, because it is so unnecessary. Approximately 100% of other languages do not have this problem, by having visibility modifiers at the method definition level. In fact, it even works in Ruby, but I digress.

Ignored Values

Some APIs will use values that are easy to ignore, once again leading to errors.

While I don’t want to seem like I pick on ActiveRecord, it contains examples within reach.

def update
  user.update(user_update_params)
  user.save

  respond_with(user)
end

In this example, the return value of user.save–a Boolean indicating whether the persistance was successful or not–is not checked. The error case, when save fails, is not handled. ActiveRecord doesn’t help nor guide towards handling it, either.

If you think your code is impervious to this problem, I suggest you look at your test suite. If you’re using save and not save! to setup objects, and unless you have very high code hygiene, chances that at least one started failing since you wrote it.

Missing Coupling

APIs sometimes need things to be coupled, but don’t express it. For example, in Ruby, any object can be a Hash key by defining two methods: hash and eql?. However, this is not encoded at runtime. To make things worse, the Object class defines an implementation based on object equality.

As a result, it’s easy for developers to redefine either of the two methods but not both. This can easily lead to situations where the objects seem to be valid hash keys, until there two items end up in the same bucket, or, conversely, when two items should fold together, but don’t.

Extending Self

The usage of extend(self) in module is probably one of my biggest pet peeves. It’s used to add methods to the singleton class of a module, effectively allowing the module to receive the methods it defines. Ex:

module Foo
  extend(self)

  def foo # 1
    :foo
  end
end

Foo.foo # 2
# => :foo

In the previous example, the module Foo defines the method foo (#1) which is available on Foo (#2) due to the extend(Foo). Not only does this idiom produce a complicated object, the fact that it’s an idiom affords users some errors.

I think people fail to consider the implications of these modules. Should Foo be used as a singleton, or should it be include’d, as modules are? In the previous example, it doesn’t matter. When you start using instance variables and state, it does.

`super` vs `super()`

In Ruby, as we know, parentheses are optional, unless they aren’t. The usage of super is such an example, where super (without parentheses) is semantically different to super() (with parentheses).

class Parent
end

class WithParentheses < Parent
  def initialize(var)
    @var = var
    super()
  end
end

class WithoutParentheses < Parent
  def initialize(var)
    @var = var
    super
  end
end

WithParentheses.new(1) # 1
# => #<WithParentheses:0x000...>

WithoutParentheses.new(1) # 2
# => ArgumentError: wrong number of arguments (given 1, expected 0)

This example shows the semantic difference between both versions.

The reason is that super (without parentheses) sends the arguments verbatim, whereas super() (with parentheses) sends no argument.

Conclusion

I hope this post has opened your eyes on the amount of affordance for errors offered by our languages and APIs. I hope you’ll start noticing them in the code you’re writing, and you’ll strive to remove as many as possible.

Post Scriptum

My list contained many other affordances that didn’t make the cut for this post. To name a few:

HashWithIndifferentAccess blurring the line between String and Symbol
validates_uniqueness_of is racy by default
assert(obj, message) is easily mistaken with assert_equal(a, b)
config(default_value: :false) (using a symbol where a boolean was expected)
ActiveRecord scopes behaving like Array but not quite
Using of structureless markup languages (YAML)

If you wish to contribute with more examples, please share them in the comments.

Refactoring Common ActiveSupport::Concern Patterns

Mon, 25 Feb 2019 20:00:00 +0400

Following my Short Rant on ActiveSupport::Concern, I’ve been asked how to refactor the code to make it stop using it, or write new code without it. I thought I’d share the patterns that have worked for me so far.

What is `ActiveSupport::Concern`?

ActiveSupport::Concern is a module which other modules can extend to get its features. It allows for easily (note: easy, not simple) applying modifications to the receiver module and its singleton class, as well as triggering hooks when the module gets include’d.

The following code contains all the marks which identify ActiveSupport::Concern (later AS::C):

module Concern
  extend(ActiveSupport::Concern)

  included do # 1
    puts("Hello from #{self}")
  end

  module ClassMethods # 2
    def baz
    end
  end

  class_methods do # 3
    def bar
    end
  end
end

module ReceiverModule
  include(Concern) # 4
end

The previous code uses all the AS::C features, which are (annotated in the code):

Setting up a callback, for when the module is included (4). The callback is class_eval’d on the receiver module, in our case ReceiverModule.
Open (or reopen) the ClassMethods module. When Concern is included in ReceiverModule, AS::C will also do ReceiverModule.extend(Concern::ClassMethods).
Same as 2, different style.
ReceiverModule uses our Concern module. The result is that ReceiverModule’s singleton class will have both baz and bar, and the code will print "Hello from ReceiverModule".

Another pattern you may see is the following:

module AnotherConcern
  include(Concern)
  extend(ActiveSupport::Concern)

  def toto
  end
end

While AnotherConcern appears to not use any of AS::C’s features, it’s “reexporting” the hooks from Concern. This is why I often say that metaprogramming breeds metaprogramming: Concern’s use of metaprogramming forced AnotherConcern to also use metaprogramming, otherwise it would not be able to offer Concern’s functionality.

Now that we’ve identified the telling signs of AS::C (included callback, ClassMethods module, and class_methods block), we can go about refactoring away from it!

Useless Extend

Believe it or not, extending AS::C for no reason nor benefit is extremely common. It also has a nice property of being trivial to remove. You’ll be able to tell that it’s uselessly extended when the receiver module has none of its telling signs, and does not include any other modules which use AS::C.

If the module has none of these, it’s safe to remove ActiveSupport::Concern, given this code:

module ConcernModule
  extend(ActiveSupport::Concern)

  def my_method
  end
end

You can apply these changes:

module ConcernModule
- extend(ActiveSupport::Concern)

  def my_method
  end
end

`ClassMethods` only, please

Modules that use ActiveSupport::Concern with the only benefit of having the receiver subsequently extend the module’s ClassMethods. You’ll notice this pattern when the only interesting piece of code in the module is the ClassMethods module. I suspect this happens when folks find it hard to understand the difference between include and extend–which is admittedly quite hard to make–, leading them to cargo-paste this code from elsewhere.

Sidenote: to learn more about include and extend, I suggest reading my previous blog post: [The Ruby Object Model]({% post_url 2019-02-01-the-ruby-object-model %}).

The code you’d be looking at would look something like this:

module ConcernModule
  extend(ActiveSupport::Concern)

  module ClassMethods
    def a_class_method
    end
  end
end

module ReceiverModule
  include(ConcernModule)
end

The good news is that this is also trivial to fix. You can remove the ClassMethods module and move its behaviour to ConcernModule. Then replace include(ConcernModule) with extend(ConcernModule), so that the behaviour is applied on the receiver’s singleton class instead of the receiver itself.

module ConcernModule
  def a_class_method
  end
end

module ReceiverModule
-  include(ConcernModule)
+  extend(ConcernModule)
end

Another variant of this is to use a class_methods block instead of the ClassMethods module. The same refactor applies.

Callback Methods

Sometimes, AS::C is used for its included callback only. Sometimes, it will coincide that the block behaviour can be implemented in another, simpler way.

module TestHelper
  extend(ActiveSupport::Concern)

  included do
    teardown do
      clean_up_after_tests
    end
  end
end

This previous example uses the included callback to call the teardown method in Minitest. Instead of this, we can define a teardown method.

module TestHelper
  def teardown
    clean_up_after_tests
    super
  end
end

This will unfortunately only work if the hooks can also be implemented using methods.

Metaprogramming the Metaprogramming

Another variation of the previous pattern is defining the methods in the hooks, for no clear reasons. This means that every time ModuleDefiningMethods is included, it will define new versions of the foo and bar methods. Every time I’ve seen this, it was unwanted.

module ModuleDefiningMethods
  extend(ActiveSupport::Concern)

  included do
    def foo
    end

    def bar
    end
  end
end

In this case, we can simply remove the included block but keep the contents. The modules which include ModuleDefiningMethods don’t even have to change.

module ModuleDefiningMethods
  def foo
  end

  def bar
  end
end

Now that we’ve gotten our hands dirty refactoring the easy cases, let’s see what we can do about the more involved ones.

Coupling Class and Instances

I’ve often seen this kind of offense, where one tries to add behaviour to the instances of a class, and other behaviour (often configuration) to the class itself. Example:

module ParameterFiltering
  extend(ActiveSupport::Concern)

  included do
    class_attribute(:allowed_params) # 1
  end

  def filtered_params # 2
    ParameterFilter.new(self.class.allowed_params).filter(params)
  end

  module ClassMethods
    def allow_params(*param_names) # 3
      self.allowed_params = param_names
    end
  end
end

class FooController
  include(ParameterFiltering)

  allow_params(:foo, :bar, :baz)

  def create
    Foo.create(filter_params)
  end
end

What this code does:

Sets up a class attribute named allowed_params.
Defines an instance method to return the filtered params, based on which are allowed.
Defines a class-level method to set the allowed_params attribute in an “idiomatic macro”.

This code unnecessarily couples the class (FooController) with its instances. Additionally, the overuse of metaprogramming in this code makes it harder to change, say, how parameters are actually filtered.

An easy change we can make to keep the code as convenient while reducing the complexity is to move allowed_params from a “macro” to a method. The resulting code will be slightly less idiomatic, but much simpler. I think that’s a good thing.

module ParameterFiltering
  def filtered_params
    ParameterFilter.new(allowed_params).filter(params)
  end

  def allowed_params
    raise NotImplementedError # Signal to your users that they must implement this method
  end
end

class FooController
  include(ParameterFiltering)

  def create
    Foo.create(filter_params)
  end

  private

  def allowed_params
    [:foo, :bar, :baz]
  end
end

Another option we have would be to make the allowed_params an argument to the filter_params method. This would increase the convenience, as callsites can filter on different arguments.

Finally, yet another refactor would be to get rid of the ParameterFiltering module entirely. Instead, we can instantiate a ParameterFilter, bind it to a constant, and reuse the same instance of ParameterFilter for all instances of the controller (provided it doesn’t have mutable state). Object Oriented Programming has taught us favour composition over inheritance, and this approach subscribes to that philosophy.

class FooController
  ParamFilter = ParameterFilter.new([:foo, :bar, :baz])

  def create
    Foo.create(ParamFilter.filter(params))
  end
end

Unfortunately, this option is too often overlooked, even though it has powerful arguments in its favour. In our case, since the instance of ParameterFilter can be reused, we’ll be allocating less objects. The resulting code is also both simpler and easier to understand. Finally, we’ll easily be able to compose objects to obtain the behaviour we want, a task which would be much harder if we used any of the previous patterns. Ex:

class FooController
  ParamFilter =
    RejectLongParameterValues.new(ParameterFilter.new([:foo, :bar, :baz]), max_length: 30)

  def create
    Foo.create(ParamFilter.filter(params))
  end
end

Class Macro, Instance Functions

This is a slight variation on the “Coupling Class and Instances” pattern, except that the main behaviour of the module is adding a “macro” to define instance methods. This pattern tends to happen when the defined method becomes long, and developers want to extract parts of it into functions. Having nowhere obvious to put the extracted methods, we resort to also using instance methods (it’s the easiest).

module ValidatedAttribute
  extend(ActiveSupport::Concern)

  module ClassMethods
    # The `attribute` method is a "macro". The `valid?` method has been extracted from it.
    def attribute(name)
      define_method(name) do
        # work
        valid_attribute?(thing)
        # work some more
      end
    end
  end

  def valid_attribute?(attribute)
    # work
  end
end

Refactoring this is quite easy in most cases: we can make them functions. This will allow us to get rid of the ClassMethods module. It also has nice benefits: the valid_attribute? function becomes much easier to test, we don’t risk clobbering other methods with the same name, and the instances have one less level of inheritance.

module ValidatedAttribute
  # The `attribute` method is a "macro". The `valid?` method has been extracted from it.
  def attribute(name)
    define_method(name) do
      # work
      ValidatedAttribute.valid_attribute?(thing)
      # work some more
    end
  end

  class << self
    def valid_attribute?(attribute)
      # work
    end
  end
end

A Pattern I Don’t Know How To Refactor

There are still a few usage patterns of AS::C which I don’t know how to easily refactor, they would require fundamental changes. These have always been around adding another layer metaprogramming, often under the guise of convenience. Here’s an example, involving metaprogramming and ActiveRecord. The CanBeActive module adds a scope to the class, and a method to the instances. While I don’t consider this to be good practice, I don’t see a more convenient way to achieve the same results.

module CanBeActive
  extend(ActiveSupport::Concern)

  included do
    scope(:active, -> { where(active: true) })
  end

  def inactive?
    !!active?
  end
end

class User < ActiveRecord::Base
  include(CanBeActive)
end

I personally don’t worry too much about the byte size of the codebase, and I would probably skip the module in this case, and implement the same logic in all classes which use it, unless that is, the CanBeActive is actually a concept my application uses, ex: if I had a ActivationController which accepts any CanBeActive resource. That is, I would add this module not as a way to share code, but as a way to identify a common concept.

Conclusion

Hopefully this post has proven that removing occurrences of ActiveSupport::Concern is generally easy, if not trivial. Often it can be removed without further changes. Other times, it just requires understanding the difference between include and extend, or knowing if methods can be used instead of “macros”. Sometimes it’s about getting to a better OOP design, but mostly, it’s about combining objects rathern than piling more layers of metaprogramming.

And sometimes, you just have to give up and add another layer of metaprogramming, in which case feel free to use AS::C.

Comment or React

Moving Away from Medium

Mon, 11 Feb 2019 20:00:00 +0400

When I started writing, I picked Medium. I didn’t want to setup a blog, have choose a template or style, or figure out how to use an analytics platform. I just wanted to write.

When writing my Revoking the (Parentheses) Privilege post, it became apparent that Medium failed me. It has no support for syntax highlighting, requiring me to use screenshots from Carbon. I’m considering a post which will require JS to create visualizations, and it would be impossible on Medium.

I’ve since switched to using Jekyll and Github Pages. I like that all revisions of my posts will be available to everyone. I like that it’s a property I (almost) control: I’ll soon switch to my own domain name.

From Medium I miss the editor (although coming back to Vim feels nice), and most definitely the easy analytics. I’ll try to use Google Analytics, but I’m somewhat apprehensive of how that’ll go. I’ll miss the “Claps”. For this I’ll ask readers to react on the GitHub; I’ll create a pull request for each new post. Comments can live there too. I’ll miss the subscriptions, but for this I’ll use releases on the repository.

Hoping this’ll stick!

Comment or React

The Ruby Object Model

Fri, 01 Feb 2019 13:36:00 +0400

Recently I was called out. I hypothesized that some bad patterns in Ruby are caused by developers misunderstanding Ruby’s Object Model, but I had not provided them with any learning resources. In fact, I couldn’t find anything satisfying, so I decided to write this post.

Edit: I’ve been sent other resources about Ruby’s Object Model:

All I’d Wanted to Know about Ruby’s Object Model Starting Out…and Mooar!!! in which Jun Qi Tan explains what I tried to in this post, in a much more eloquent talk.
Unraveling Classes, Instances and Metaclasses in Ruby by Jeff Kreeftmeijer in the excellent Ruby Magic series.
Metaprogramming in Ruby by Paolo Perrotta has a section on the object model.

This post is aimed at developers familiar with Ruby and Object Oriented Programming. I’ll assume you have some understanding of what objects and classes are, and that you can read Ruby code without commentary. If you want to learn more about Ruby, or if this post has you itching for more, I must recommend Ruby Under The Microscope by Pat Shaughnessy. Chapter 5 goes in-depth in the data structures the Ruby VM (MRI) uses for objects and classes.

If you’d rather skip the wall of text, visit the TL; DR. Otherwise, let’s get started!

Objects

You’ll hear it often: all values in Ruby are objects, and all expressions return values. It is thus commonly said that “Everything in Ruby is an Object”. Let’s add some objects to our program. We’ll use the this code for the entire section:

class Animal
  def initialize
    @affection = 0
  end

  def pet
    @affection += 1
  end
end

class Cat < Animal
  def initialize(name)
    @name = name
    super()
  end

  def pet
    puts("purrr")
    super
  end
end

coco = Cat.new("coco")
coco.pet
# => prints "purrr"

Objects in Ruby are just a combination of state—the values of instance variables—, with a class attached to it. The class of an object defines the methods the object has access to. Ruby is easily introspectable, so we can ask it about the state and class of coco.

# State
coco.instance_variables
# => [:@name, :@affection]

# Class
coco.class
# => Cat

coco’s state contains two instance variables: @name and @affection. Its class is Cat. Nothing surprising so far.

The word “class” in Ruby can mean multiple things: the instantiatable class which provides behaviour to its instances, the class object, or both. When talking about an object’s class, we generally intend to describe the methods defined by that class. For this purpose, we will use the word behaviour from now on.

Classes

In the Objects section we learned that classes have multiple facets, and one of them is providing the behaviour of instances of that class. This is done by setting up an ancestor chain (also called “inheritance chain”). They can be inspected at runtime using the ancestors method. This allows us to clearly see that coco contains the behaviours defined by Cat, Animal, Object, and so on.

1
2

coco.class.ancestors
# => [Cat, Animal, Object, Kernel, BasicObject]

The ancestor chain is a linked list. For Cat, it looks like this:

Whenever you call the pet method on coco, the Ruby VM will find the behaviour in coco’s class’s ancestor chain (Cat’s, that is), from left to right: starting with Cat, then Animal, and so on, until the method is found. When calling super within that method, Ruby would find the next ancestor defining a behaviour for the pet method, and invoke it, in this case, the one defined in Animal.

_{In the previous figure, ancestors after Animal (Kernel and BasicObject) have been omitted.}

To know which methods are defined on each ancestor in the ancestor chain, use the instance_methods method. The boolean argument specifies whether to also include the methods defined by the class’s other ancestors.

1
2

Cat.instance_methods(false)
# => [:pet]

In Ruby, classes are also values, which means they are also objects. This is interesting; it means that in addition to defining methods, classes are also the combination of state and a reference to a class.

For this facet (objects which are instances of the Class class), we will be talking about class objects.

Class objects have a method named new, which comes from the behaviour defined by the Class class.

1
2

Cat.method(:new).owner
# => Class

The default behaviour of the new method is to return a new object: it instantiates the class.

1
2
3

coco = Cat.new("coco")
coco.class
# => Cat

While this method can be changed by any class in the ancestor chain, this privilege is rarely abused and is frowned upon, but know that one could do it.

For some, it may be surprising that the Class class is a subclass of the Module class, meaning that all class objects are also Modules. In the next section, we will talk about modules; remember that many things will also apply to class objects.

1
2

Cat.class.ancestors
# => [..., Module, ...]

Modules

module Quadruped
  def feet_count
    4
  end
end

Modules, like classes, have two facets: they are values (thus, objects), and they can define behaviour for other objects. Unlike class objects however, Module objects do not have a method named new, and cannot be instantiated directly.

Quadruped.new
# Traceback (most recent call last):
#         1: from (irb)
# NameError (undefined method `new' for class `Module')

Since Modules cannot be instantiated nor subclassed, they need another way to be used as an object’s behaviour. This is done by using the include, prepend, and extend methods on Module objects (and on class objects!). I’ll describe include and prepend now, but keep extend for later.

Include

When using include(A), the module (A) is inserted in the ancestor chain of the receiver module. Its methods are thus made available on instances of the receiver.

class Cat < Animal
  include(Quadruped)
end

# Or the equivalent: `Cat.include(Quadruped)`

The previous code will add Quadruped as an ancestor to Cat, making its methods available to all instances of Cat.

coco.class.ancestors
# => [Cat, Quadruped, ...]

> coco.feet_count
# => 4

Note that include adds the module to the ancestor chain after the receiver; Quadruped appears after Cat.

In the Objects section, we said that the ancestor chain’s order is used to determine which method gets called first. Using another example, we can confirm this:

module A
  def foo
    puts("in a")
  end
end

class B
  include(A)

  def foo
    puts("in b")
    super
  end
end

B.new.foo
# prints:
#    in b
#    in a

Some people are surprised that this behaviour remains unchanged if we move include(A) to after the method definition. The important thing to remember is that an object’s behaviour is defined by its class’s ancestor chain; moving include(A) lower down has no impact on the ancestor chain.

Prepend

Prepend is very similar to include with one very important distinction: it adds the module before the receiver.

class Dog
  prepend(Quadruped)
end

Dog.ancestors
# => [Quadruped, Dog, ...]

This means that behaviours defined by Quadruped will have precedence over those defined by Dog. The following figure shows the distinction: prepend adds the module to the beginning of the ancestor chain, while include adds it right after the receiving module.

Singleton Classes

dora = Cat.new("dora")
# Dora has mitten paws
def dora.number_of_toes
  22
end

dora.number_of_toes
# => 22

Earlier in this post, I said that objects are the combination of state and a class. This is slightly less than accurate. In fact, two objects instantiated from the same class, are not necessarily of the same type. This is (you probably guessed it from the section title) because of the singleton class. The truth is, every object in Ruby possesses its very own class, of which it is a singleton. You may also have seen “eigenclass”—another word for singleton class—, or “metaclass”, which is specifically a Class object’s singleton class. In our code, dora and coco don’t have the same class, which explains why coco does not have the number_of_toes method:

coco.number_of_toes
# Traceback (most recent call last):
#         1: from (irb)
# NoMethodError (undefined method `number_of_toes' for #<Cat:0x00007fe5201b0f78 @name="coco">)

As such, the “true” class of an object is its singleton class.

dora.singleton_class.instance_methods(false)
# => [:number_of_toes]
dora.singleton_class.ancestors
# => [#<Class:#<Cat:0x00007fe52016e3a8>>, Cat, Quadruped, ...]

The weird #<Class:#<Cat...>> up there means “the singleton class of the Cat object 0x00007fe52016e3a8”, which is dora:

1
2

dora
# => #<Cat:0x00007fe52016e3a8 @name="dora"> # notice the `0x00007fe52016e3a8`

The following diagram shows the hierarchy of both coco and dora, with their respective singleton classes; only dora’s singleton class defines the number_of_toes method.

Astute readers will correctly understand that, in many cases, an object’s singleton class can be elided (omitted) by the virtual machine. In fact, if the VM did not elide most of them, no Ruby program would be able to run. This is because class objects also have singleton classes, and Singleton classes are also class objects, which themselves also have singleton classes… and so on recursively. In our previous example, coco’s singleton class can be elided since it neither defines methods, nor has state.

Methods defined on a class object’s singleton class are sometimes erroneously called “static functions”. This nomenclature is misleading; we should avoid it. Using it sets us up for expectations the Ruby VM cannot meet. The reason is, they are not functions, they are nothing more than methods defined on a class object’s singleton class. Additionally, constants in Ruby are not truly constant, so these methods are not static either.

There are several ways to define methods on a class’s singleton class.

def Cat.feline? # Like the `number_of_toes` example
  true
end

class Cat < Animal
  def self.feline? # `self` is `Cat` here, so this is exactly the same as the previous example
    true
  end
end

class Cat < Animal
  class << self
    def feline?
      true
    end
  end
end

In this last example, class << self is a special syntax which opens self’s singleton class, in this case, Cat’s, similar to how class Cat opens the Cat class. Everything that can be done in Cat to affect its instances can be done within class << self to affect the only instance of Cat’s singleton class, which is Cat itself. (oh god, I’m going to lose people over this overuse of the words “class” and “singleton”, aren’t I?)

Of these 3 forms however, there is a clear “better way” in terms of simplicity and predictability: class << self. Other means will fail the programmer’s expectations more often than not, e.g. around method visibility:

class Cat < Animal
  private

  def self.are_the_best?
    true
  end
end

One would expect the are_the_best? method defined by Cat’s singleton class to be private, but it is not.

1
2

Cat.are_the_best?
# => true

I didn’t intend to talk about method visibility in this object model post, but let’s just briefly go there, to show an example of Ruby failing to meet expectations. The reason for this unexpected behaviour is that private is not a keyword, it is a method. In this case, it will be received by Cat, allowing it to make any new method defined on it as private. Cat’s singleton class however, does not receive this method call to private. As a result, it is not aware that it should change the visibility of methods that will be defined.

Had we used the class << self syntax instead, it would have worked as expected:

class Cat < Animal
  class << self
    private

    def are_the_best?
      true
    end
  end
end

Cat.are_the_best?
# Traceback (most recent call last):
#         1: from (irb)
# NoMethodError (private method `are_the_best?' called for Cat:Class)

So far, we’ve seen Objects, Classes, Modules, and Singleton Classes. This is a great time to take a break! In the next section, we’ll see extend, and singleton class inheritance.

Extend

The extend method confuses many people: how is it different from include and prepend? When should they use one, or the other? To answer that question, consider the following code:

module D
  def a
    "Hello? This is D"
  end
end

class E
  include(D)
end

class F
  extend(D)
end

Can we predict what behaviour we can expect from E and F? If we recall from the previous sections, an object’s behaviour is provided by its class’s ancestor chain. Let’s try it:

E.ancestors
# => [E, D, Object, ...]
F.ancestors
# => [F, Object, ...]

That’s interesting! We can expect instances of E to have D’s behaviour, but not instances of F.

1
2

E.new.a
# => "Hello? This is D"

So far so good, E does indeed have D’s behavour.

F.new.a
# Traceback (most recent call last):
#         1: from (irb)
# NoMethodError (undefined method `a' for #<F:0x00007febf409e218>)

Success! We correctly predicted this too. If instances of F don’t have D’s behaviour, could the class object F have it then? To predict it, we can ask F’s singleton class!

1
2

F.singleton_class.ancestors
# => [#<Class:F>, D, #<Class:Object>, ...]

It does have D!

1
2

F.a
# => "Hello? This is D"

What does this tell us? It looks like extend applies to the singleton class’s the same changes which include does to the class’s. If that were the case, it means we could achieve the same results by calling include within the singleton class instead.

class D
  class << self
    include(D)
  end
end

D.singleton_class.ancestors
# => [#<Class:D>, D, #<Class:Object>, ...]

D.a
# => "Hello? This is D"

It works as predicted!

I should note that this is not exactly true, extend and singleton_class.include are slightly different. Whenever a module gets added to the ancestor chain of another module, the first module gets a callback on one of three methods: prepended, included, extended. Some side-effects could be expected from these methods, and you may be required to use a specific method to get these side-effects.

module Mod
  def self.included(receiver)
    puts "Mod is included by #{receiver}"
  end

  def self.prepended(receiver)
    puts "Mod is prepended by #{receiver}"
  end

  def self.extended(receiver)
    puts "Mod is extended by #{receiver}"
  end
end

module G
  include(Mod)
end

module H
  prepend(Mod)
end

module I
  extend(Mod)
end

# prints:
#   Mod is included by G
#   Mod is prepended by H
#   Mod is extended by I

Extend on All Objects

Did you know that most objects have the same extend method? Now that we know that extend modifies the behaviour of the receiver (by adding the argument to the receiver’s singleton class’s ancestor chain), we can predict what happens if we use extend directly on any object*.

module OwnedByGuillaume
  def owner
    "Guillaume"
  end
end

coco.extend(OwnedByGuillaume)

coco.singleton_class.ancestors
# => [..., OwnedByGuillaume, ...]

coco.owner
# => "Guillaume"

As predicted, the receiver (coco) has the behaviour offered by OwnedByGuillaume.

_{*although calling extend on any object is perfectly valid Ruby, I urge you to either not use it, or use it very parsimoniously}

Singleton Class Inheritance

In Ruby, singleton classes are subclasses of their instance’s original class. Heh, this is a bit hard to follow, let’s do an example.

1
2

coco.singleton_class.superclass
# => Cat

In the previous code, we can see that coco’s singleton class is a subclass of Cat, like Cat is a subclass of Animal. For class objects, their singleton class are subclasses of their superclass’s singleton class: Cat’s singleton class is a subclass of Animal’s singleton class, which is itself a sublcass of Object’s singleton class, and so on.

1
2

Cat.singleton_class.ancestors
# => [#<Class:Cat>, #<Class:Animal>, #<Class:Object>, ...]

The next figure illustrates the relationships between class objects, their singleton classes, and their respective superclasses.

Modules, however, are not inherited at both levels (class and singleton class behaviours). Instead, the programmer picks which ancestor chain will be impacted by using either prepend or include (class), or extend (singleton class).

module Included
end

module Extended
end

class L
  include(Included)
  extend(Extended)
end

class M < L
end

M.ancestors
# => [M, L, Included, ...]

M.singleton_class.ancestors
# => [#<Class:M>, #<Class:L>, Extended, ...]

As you can see, while L appears in M’s ancestors, Extended does not, and while L’s singleton class appears in M’s singleton class’s ancestors, Included does not.

Conclusion (or TL; DR)

Here’s what I hope you take away from this post:

Objects are the composition of state and a reference to a class.
The “real” class of any object is its singleton class.
Class are just normal objects, and their class named Class.
prepend and include affect the behaviour offered by the receiver.
extend affects the behaviour of the receiver, through its singleton class.

Revoking the (Parentheses) Privilege

Mon, 03 Dec 2018 21:00:00 +0400

For years, Rubyists (including where I work) have enjoyed the privilege of omitting parenthesis around method call arguments. Last week, we merged a pull request to our style guide revoking that privilege: parenthesis will become mandatory for all method calls with arguments.

Don’t let anyone fool you, Ruby is a complicated language. It’s syntax is full of quirks, pitfalls, and gotchas. It’s a minefield for newcomers and veterans alike. Despite that, it can be an elegant language; we just have to choose which subet of the language to use. We chose that this subset doesn’t allow omitting parentheses on methods which have parameters.

The discussion on wheter to enforce parentheses or not was a recurrent one. The arguments in favour of enforcing were generally around predictiblity, or removing the surface for mistakes. The arguments against cited that enforced usage of parentheses is inconsistent with Ruby in the wild, it’s not idiomatic. While arguments against have prevailed until now, the tipping point has been reached this week. Let’s examine what happened.

The Final Straw

Last week, I stumbled on the following piece of code in a slide deck describing a new feature:

1
2
3

assert nodes.all? do |node|
  !node["content"].empty?
end

Seasoned Ruby developers may understand the problem with this code, though it is far from self-evident. The issue is that block precedence is different for do/end and {} blocks. As a result, the two following blocks are not identical:

assert nodes.all? do |node|
  !node["content"].empty?
end

assert nodes.all? { |node|
  !node["content"].empty?
}

To understand the block precedence differences, we can group the expressions using parentheses to see what the VM will evaluate:

assert(nodes.all?) do |node|
  !node["content"].empty?
end

assert(nodes.all? { |node|
  !node["content"].empty?
})

As you can see, they are not at all the same. The first case sends the return value of nodes.all? to assert, along with a block. The assert method does not expect a block, but also doesn’t fail: in Ruby, all methods will implicitly accept a block, regardless of whether they intend to or not.

With this in hand, I wanted to know how many other occurrences there were. I redefined assert to raise whenever it was called with a block, in order to know if the issue was a one-off, or systemic. There were 27 occurrences, out of which 7 didn’t pass once corrected. 27 mistakes counting only calls to assert. I haven’t checked further to see if other methods were unintendly called with a block that was meant for another receiver, as it’s pretty much impossible to script.

This find was the straw that broke the camel’s back. Something had to be done.

This example is (unfortunately) not the only problem with omitting parentheses. So many things can (and will!) go wrong.

What Else Can Go Wrong

Beyond inadvertently sending a block to the wrong method, many things can happen to Ruby methods. We’ll explore only the things that involve omitting parentheses. Every method accepting variadic or optional parameters is vulnerable to a slew of hard-to-detect issues. The following sections will show a few of these potential issues.

Disclaimer: Ruby developers like to omit parentheses moreso on what they call “macros” than on what they consider to be normal methods. In the code examples, “macros” will be over-represented.

Note about macros: there is no such thing as a language-level macro in Ruby, like you would find in C, Elixir, or Rust. Ruby macros are only social contracts, and have various definitions. Some people define it loosely as the methods that could reasonably be macros in other languages. This would include assert, has_many, extend and include, to name a few. Others would more formally define it as a method call with an implicit receiver where the receiver is a Module. Because I can’t possibly be expected to learn the list of all methods which fall in the first definition, and that the first definition is generally a superset of the second, I personally tend to subscribe to the 2nd definition.

Extra Trailing Commas

Consider the attr_reader method, on which it is generally accepted to not put parentheses. It’s variadic nature means that you can call it with any number of arguments.

class Foo
  attr_reader :a,
    :b,
    :c

  def initialize
    @thing = true
  end
end

The attr_reader method is just a regular method, and unlike in some other languages, it’s arguments can be the result of other expressions.

Unwittingly removing the last line change will not be a syntax error but may greatly impact the behaviour of the code:

class Foo
  attr_reader :a,
     :b,
-    :c

  def initialize

The subtlety lies in the fact that def initialize will return the :initialize symbol, which will get passed to attr_reader as the 3rd positional argument, effectively making this code attr_reader(:a, :b, :initialize). Suddenly, the Foo class has an initialize attribute reader.

This could very well pass code review, because it is so subtle.

This extra trailing comma is only a problem because the arguments to attr_reader were not within parentheses; attr_reader(:a, :b,) would not result in the same problem.

Add parentheses.

Missing Trailling Commas

Extra trailing commas are not the only offenders; missing trailing commas are also problematic. Imagine a refactorig scenario that leads to this perfectly valid code:

def can_access?(resource, allowed_users_and_orgs, denied_users = [])
  # work
end

can_access? load_blog_post_from_params(params), @users_allowed_on_blog_posts
  @users_denied_from_blog_posts

The missing trailing comma makes @users_denied_from_blog_posts its own, valid expression which will effectively no-op. It is not sent to the can_access? method. Perhaps this will be caught by your test suite, perhaps it will not.

Again, using parentheses would’ve prevented the problem, making the code syntactically invalid.

Add parentheses.

Semantic White Space

Whitespace is sometimes semantic in Ruby, and this is generally around method calls, except if preceded by a paren, a comma, a backslash, a colon, and perhaps other punctuation. The simple fact that one has to memorize this rule (and that I don’t know it) is cause for concern.

These blocks are equivalent:

private(:foo)

private(
  :foo
)

private \
  :foo

These are not, although both are perfectly valid Ruby:

private :foo

private
  :foo

Again. Add parentheses.

Learning Impediment, Cognitive Load

When developers are introduced to Ruby (and even more so to Ruby AND Rails), they have to learn a great many things. For reasons I still don’t understand, we teach them that somehow, attr_reader, extend, private, has_many, and so many others have special statuses; they’re not just regular methods. Yet they are. We’re actively hurting their learning experience, for legacy reasons.

Once they’ve learned that all methods are the same, they still have to remember and recall an ongoing list of which methods take parentheses, which don’t. This is no easy feat, and adds to the endless stream of decisions one has to make when writing code.

As a thought experiment, I was sent this example by a coworker, stating that they could not possibly be expected to add parentheses. The code is copied verbatim:

expect { foo.do_it }
  .to not_change { foo.total }
  .and change { bar.count }.by(1)
  .and change { baz.count }.by(-1)

I must admit I’ve had great difficulty parsing that code. What gets sent to what? What chains on what?

The trick with this example is that the indenting is wrong (but copied verbatim). In fact, the first .and chains on the result of not_change {}, not the result of the previous to, as the indenting suggests. The second .and chains on the result of by(1). Writing this code with parentheses even with the wrong indenting makes this clear:

expect { foo.do_it }
  .to(not_change { foo.total }
  .and(change { bar.count }.by(1)
  .and(change { baz.count }.by(-1))))

Yes, add parentheses.

Consistency and Readability

A large number of method calls have much more than one argument. Sometimes, they are long enough to span multiple lines. They are written sometimes adding parentheses, sometimes ommitting them, and some other times using \.

attribute \
  :first_name,
  :last_name

has_many :blog_posts,
  -> { order(id: :asc) }, autosave: false, inverse_of: :author, dependent: :destroy

has_many(
  :subscriptions,
  class_name: "Blog::Subscription",
  foreign_key: "author_token",
)

Some may consider that has_many(:posts) or attr_reader(:name) is off-putting, while others may not; it is a subjective matter. I think we can objectively agree that the above code is inconsistent. If for nothing else, our style guide should keep our code consistent.

Just add parentheses.

Editors

Today’s editors are pretty smart regarding parentheses. They can highlight matching sets of parens, select the internals, navigate to the end. This is all manual labour of parsing code that can be delegate to our tooling.

The Decision

Now that we understand many of the issues, we can devise ways to avoid them. We’ve found two ways:

Add a set of new rules to our style guide that prevent all these cases
Enforce parentheses everywhere

On the surface, option 1 may seem feasible. After all, if we understand all the problems, surely we can add enough rules to cover all of them. Maybe that’s true, maybe someone can write these rules, and be diligent enough such that none will conflict. That, however, serves to increase the cognitive load.

Option 2 is a simple rule. One rule. Occam’s Razor suggests it’s the best approach.

We believe that the benefits of enforcing parentheses significantly outweigh it’s downsides. Besides, it simplifies the way we write our software, even if just a little.

We went from a complicated, noninclusive decision tree,

To a much simpler, more inclusive decision tree.

Final Considerations: About Idiomatic Code

In general, I believe following the community guidelines is preferrable. In light of all the evidence provided, I cannot hold that belief; I have to believe that writing safer and better software is more important than following the style used by others.

Idiomatic Ruby once was the Seattle Style. I don’t see anyone arguing we should go back. The idiomatic style is just the style which is in vogue at the moment. And it changes, all the time, as new informations, new ideas, new authors come to light. We can be the forbearers of this new, idiomatic style.

Short Rant about ActiveSupport::Concern

Mon, 19 Mar 2018 21:00:00 +0400

This is a copy/paste of a comment I made on an internal pull request. I had been tagged on it because on my hard stance against ActiveSupport::Concern, asking me to clarify my objections. I’ve reworded my reply where it made sense.

Here is the code on which I was asked to comment:

module Component
  module AcquiredInformation
    extend ActiveSupport::Concern

    included do
      class << self
        class_attribute :component

        method = method(:component)
        self.component =
          Component::Discovery.from_method(method) ||
          Component::Discovery.fallback_component
      end
    end

    module ClassMethods
      def inherited(klass)
        klass.component =
          Component::Discovery.from_caller(caller) ||
          Component::Discovery.fallback_component

        super
      end
    end
  end
end

My Reply

My main problem is that ActiveSupport::Concern (later AS::C) encourages bad object-oriented design, while simultaneously having programmers forfeit their understanding of the object model.

I don’t want to dwell on what Ruby’s object model is; it’s the topic of an other discussion and most of you already know it. One thing is important to understand is that for class MyClass, the instance returned by MyClass.new and the class MyClass itself both are proper objects (later denoted instance and class, respectively). Great care must be applied in designing both, and both must not be confused for the other.

OO Design

AS::C conflates the class and the instance design by encouraging a single module that acts upon both.

In all cases where instances are used, the class itself is a factory. Adding more functionality to the class must take that fact into account to not violate the SRP.

Furthermore, for those that don’t know me, here’s one thing you must know: I fundamentally believe that naming things correctly is a prerequisite for good design. Naming concepts and objects is the best way we have to communicate meaning to one another, it’s basically one of the greatest decomposition technique at our disposal.

AS::C robs us of this ability to name the things by imposing a ClassMethods name to add features to the class object. The ClassMethods suggests that the module is just a bag of methods without necessitating a common, named concept.

Consider the CarrierService class (ed: an internal class), which, let’s remind ourself, is a factory generating CarrierService instances. It apparently has many other roles, of which most aren’t properly named.

> CarrierService.singleton_class.ancestors
[
 IdentityCache::ShouldUseCache::ClassMethods,
 IdentityCache::QueryAPI::ClassMethods,
 IdentityCache::ConfigurationDSL::ClassMethods,
 IdentityCache::CacheKeyGeneration::ClassMethods,
 IdentityCache::BelongsToCaching::ClassMethods,
 EncryptableAttributes::ClassMethods,
 ...

What does it mean to say that CarrierService is a IdentityCache::ShouldUseCache::ClassMethods? Is it a grab-bag of methods related to IdentityCache, or is it a behaviour compatible with the factory role?

Object Model

AS::C has programmers forfeit their understanding of what it means for an object to either include or extend a module, by having them always include, and use the self module to act upon the instance’s class, and ClassMethods module to act upon the class’s class, even in cases where only the latter is necessary.

Taking the code-at-hand as an example. The only behaviour we want to change it the class’s; the instance should remain unmodified. To do so, the code using AS::C does many things:

Define a Component::AcquiredInformation module and makes it inherit from AS::C
Defines a ClassMethod module
Upon defining instances as inheriting from Component::AcquiredInformation, it reopens that instances’s class to define an attribute on it
Upon defining a class that inherits from Component::AcquiredInformation::ClassMethods, it modifies the class to overwrite the attribute

Now consider a module built for the same purpose but that doesn’t conflate instance and class. It could use the extended hook to define the attribute, and the inherited hook to overwrite the attribute.

module Component
  module AcquiredInformation
    def self.extended(base)
      base.class_attribute :component

      method = base.method(:component)
      base.component =
        Component::Discovery.from_method(method) ||
        Component::Discovery.fallback_component
    end

    def inherited(klass)
      klass.component =
        Component::Discovery.from_caller(caller) ||
        Component::Discovery.fallback_component

      super
    end
  end
end

I agree that this still isn’t the greatest OO design, but at least it’s radically simpler.

Because I struggle to find a single case in which using AS::C actually provides a better design than not using it, I am a hardliner of never using it.

Comment or React

Mistaking Authentication for Identification

Tue, 21 Apr 2015 20:00:00 +0400

Disclaimer: I am not a security expert, nor a systems expert. The following text is tinted by my understanding and experience, and probably contains mistakes or misunderstandings.

Earlier this year, I accidentally uncovered a flaw in GitHub, Heroku and many other similar providers. The flaw essentially allows a denial of service to some users with little effort from the attacker. The situation has not been fixed, and it likely will not be. At the center of the problem is the fundamental mistake of thinking that authentication can be a substitute for identification.

Identification is a process through which one claims an identity. One person may have several identities. For example, GitHub knows me under the identity of gmalette. My gamer tag on Steam is Wako. Anyone can claim those identities; anyone can try to login on GitHub using gmalette or on Steam using Wako. We need a way to verify the authenticity of that identity claim, a way to make sure the user really is who they pretend to be.

Authentication is the process through which one verifies a claimed identity. Typically, the person being authenticated will produce a document that assures they own the identity. Such documents can be a passport, a credit card’s CVV code, a password, etc.

On the internet, we generally use password authentication. That is, when you connect to a website, you provide your identity (username, email address, etc). The server will find the account matching that identity, and use a password for authentication.

What happens when you mistake authentication for identification? What if somehow, your identity was directly related to the authentication mechanism? You can imagine a website where you only have to enter a password to be logged in. The password will be hashed and salted for security, but the system will keep the first 3 characters to identify the user. When a user logs in using a password, the system will find the user using the first 3 characters, and then authenticate using the full password.

Imagine Alice choses the password “123456” (identified by “123”), Bob chooses the password “password” (identified by “pas”). Bob and Alice can both use the system without any problem. That is, until Alice changes her password to “password123456” (also identified by “pas”). Now when Bob enters “password”, he will be wrongly identified as Alice, but will be unable to authenticate because he does not know the password. Bob will be locked out of his account even if it had previously worked. Such a system couldn’t exist, could it?

Most Git shells I’ve interacted with use a similar process of identification. More specifically, most Git shells identify the user while negotiating an SSH key, before the authentication happens. During the negotiation process, the client SSH will find all the keys it knows. For each key, it will send the fingerprint of the public key to the server. If the key is known to the server, it will send a challenge and SSH will use the private part of the key to respond to the challenge. The challenge may vary based on a few factors, but it always serves to prove that the user being authenticated owns the private key. One type of proof could be to sign a random piece of data. Signing is an operation that can only be performed using the private key, and easily verified using the public key. If a malicious user sends a known fingerprint but can’t respond to the challenge (because they don’t have the private key), they will not be authenticated and will not have access to the user’s data. But there is another, subtler way this process can be used for nefarious purposes.

The thing is, you can (and should) expect public keys to be just that — public. You should behave as if everyone on the internet knows your public keys. In fact, many services expose the public keys of their users. GitHub exposes them on their public API without any need for authentication; here are mine. From a security perspective, that’s understood, and not a problem.

When you sign up to GitHub or Heroku, you will typically add your public key to your account. That allows cloning repos using urls such as “git@github.com/user/project”. For convenience reasons, those services usually allow using more than one public key. Because the identification is based on the public key fingerprint, they will prevent two accounts from having the same public key, which can restrict the attack I’m about to describe, but not by much.

Let’s revisit the previous example, this time using public keys. Bob signs up for GitHub, and uses a key named “id_rsa”. Bob then signs up to Heroku, using a different key named “id_rsa_heroku”. Since SSH will by default always send the keys in the same order, we’ll pretend the key “id_rsa” is sent first. Let’s examine the SSH debug log when Bob connects to Heroku.

[1] debug1: Next authentication method: publickey
[2] debug1: Offering RSA public key: /Users/bob/.ssh/id_rsa
[3] debug1: Authentications that can continue: publickey
[4] debug1: Offering RSA public key: /Users/bob/.ssh/id_rsa_heroku
[5] debug1: Server accepts key: pkalg ssh-rsa blen 277
[6] debug1: Authentication succeeded (publickey).

The following happened:

[2] — Bob offered his first key (id_rsa)
[3] — the server tells Bob it doesn’t know the key; try another one
[4] — Bob offers the second key (id_rsa_heroku)
[5] — The server knows the key. It’s to Bob’s account. It produces a challenge
[6] — authentication happens, and Bob is successfully logged in.

Alice knows all the keys, so she adds “id_rsa” to an empty Heroku account (remember, Bob uses “id_rsa_heroku”). What happens when Bob tries to connect to his Heroku account?

[1] debug1: Next authentication method: publickey
[2] debug1: Offering RSA public key: /Users/bob/.ssh/id_rsa
[3] debug1: Server accepts key: pkalg ssh-rsa blen 277
[4] debug1: Authentication succeeded (publickey).

The debug log of the SSH connection reads as follows:

[2] — Bob’s SSH client sends the key “id_rsa”
[3] — The server knows this key. It’s to Alice’s account. It produces a challenge
[4] — Bob successfully responds to the challenge (he owns the private key)
Bob is logged into Alice’s empty account
Bob cannot access his own data

This can hardly be classified as an attack, yet Bob is not able to connect to his account. The message Bob will get is: “Your account alice@email.com does not have access to awesome-project”, which will probably leave most users dumbfounded. This denial of service will cause headaches to advanced users, and will seriously ruin the day of less technical people. To be fair, Bob is not completely locked out. SSH allows specifying which key to use when connecting to specific servers.

A simple solution would be to avoid the single user login git@service.com, and use that as identification, for example gmalette@service.com.

To leave you with a simple takeaway, identification and authentication serve a fundamentally different purpose. Thinking they can be interchanged can lead to frustrating issues for users. Please understand what the difference is, and build systems accordingly.

Thanks to Lydia Krupp Hunter and Richard McGain.

Comment or React

Guillaume's Horrible Code-Along Blog

#guillaume-rant-palace

#guillaume-rant-palace

GraphQL ❤️ Sorbet and Unit Tests

Primer

API

Why Unit Tests

Why Static Typing

Practical Example

Testing Inputs

Testing Return Values

Adding Types

Changing Things

Input Narrowing

Output Widening

Conclusion

Type Variance Explained To a Ruby Developer

Type Variance

The Curious Case of Arrays

Sources Are Covariant

Sinks Are Contravariant

Read and Write, Put and Take

Conclusion

Affordance for Errors, part 3

Design Example: Reservation Manager

Who Are The Users?

Idiomatic API

Identifying Affordance for Errors

Removing the Affordances

Conclusion

Affordance for Errors, part 2

How Others Have Solved Similar Problems

ActiveRecord’s Errors API

N + 1

Illegal States

String, Hash, and other primitives

State Machines

Incomplete Booleans

Ruby’s Visibility Modifiers

Ignored Values

Missing Coupling

Conclusion

Affordance for Errors, part 1

Why Bother?

Examples of Surfaces for Errors

ActiveRecord’s Errors API

N + 1

Illegal States

Incomplete Booleans

Email is a String, Struct is a Hash

Ruby’s Visibility Modifiers

Ignored Values

Missing Coupling

Extending Self

super vs super()

Conclusion

Post Scriptum

Refactoring Common ActiveSupport::Concern Patterns

What is ActiveSupport::Concern?

Useless Extend

ClassMethods only, please

Callback Methods

Metaprogramming the Metaprogramming

Coupling Class and Instances

Class Macro, Instance Functions

A Pattern I Don’t Know How To Refactor

Conclusion

Moving Away from Medium

The Ruby Object Model

Objects

Classes

Modules

Include

Prepend

Singleton Classes

Extend

Extend on All Objects

Singleton Class Inheritance

Conclusion (or TL; DR)

Revoking the (Parentheses) Privilege

`String`, `Hash`, and other primitives

`super` vs `super()`

What is `ActiveSupport::Concern`?

`ClassMethods` only, please