quilt_rails 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 393d55d7b0940edb22882fff283debdc403bd991172f4f4fc80c8f11e9e63ca7
-  data.tar.gz: 54eab8702f1f45dcba856e79474ccbde6f575e200b4a4fbb094ffb822d5040cb
+  metadata.gz: 698a173ee3b10092312909bbee61feba9982397e474043ed6a3a77a548b2836c
+  data.tar.gz: 99d5d7844a7d1b1850df281589b5ebfa1b08ac830845f650bacd99722799dc4f
 SHA512:
-  metadata.gz: 000d1fee3b1fc1650f9f7ef9eefe5794facbdd3b05907e7d0b5e72214e7486a76a1c07f9eedd02593c3e366f6ffdcd7bf8592d1db744cdfb6d876cc3a48caec7
-  data.tar.gz: 9444a83ad67ff6298e10554bf3bf33c3a0db9b22bfd6f19f8cf918c6d31d4ed0f62cc369b3fe44867cf2bab41bf5242c991e0820c63b9c671b0313a9d4a8cb2f
+  metadata.gz: 2967e5754b5c2525da40d52fd3acc00097fbb6c3011c417c5d2118748880560bf32f7d2262eaa531e324aa53d2c9166a990da87658b418ff8a8803c677581ab7
+  data.tar.gz: 5fe683e1107e708a0a6e3bb169d37761b84b73e8dea0e296d7d469f168a4d783654961c1fb500b663efddbeeaf6834797bc917571c3696d54ff6d8d3f53b5740

data/README.md

@@ -1,63 +1,94 @@
 # quilt_rails
 
-A turn-key solution for integrating server-rendered react into your Rails app using Quilt libraries.
+A turn-key solution for integrating Quilt client-side libraries into your Rails app, with support for server-side-rendering using [`@shopify/react-server`](https://www.npmjs.com/package/@shopify/react-server), integration with [`@shopify/sewing-kit`](https://www.npmjs.com/package/@shopify/sewing-kit) for building, testing and linting, and front-end performance tracking through [`@shopify/performance`](https://www.npmjs.com/package/@shopify/performance).
 
 ## Table of Contents
 
-1. [Quick Start](#quick-start)
-   1. [Generate Rails boilerplate](#generate-rails-boilerplate)
-   1. [Add Ruby dependencies](#add-ruby-dependencies)
-   1. [Generate Quilt boilerplate](#generate-quilt-boilerplate)
-   1. [Try it out](#try-it-out)
-1. [Manual Install](#manual-installation)
-   1. [Install Dependencies](#install-dependencies)
-   1. [Setup the Rails app](#setup-the-rails-app)
-   1. [Add JavaScript](#add-javascript)
-   1. [Run the server](#run-the-server)
-1. [Application Layout](#application-layout)
-1. [API](#api)
-   1. [ReactRenderable](#reactrenderable)
-   1. [Engine](#engine)
-   1. [Generators](#generators)
-1. [Advanced Use](#advanced-use)
-   1. [Testing](#testing)
-   1. [Interacting with the request and response in React code](#interacting-with-the-request-and-response-in-react-code)
-   1. [Dealing with isomorphic state](#dealing-with-isomorphic-state)
-   1. [Customizing the node server](#customizing-the-node-server)
-
-## Quick Start
+- [Server-side-rendering](#server-side-rendering)
+  - [Quick start](#server-side-rendering-quick-start)
+    - [Generate Rails boilerplate](#generate-rails-boilerplate)
+    - [Add Ruby dependencies](#add-ruby-dependencies)
+    - [Generate Quilt boilerplate](#generate-quilt-boilerplate)
+    - [Try it out](#try-it-out)
+  - [Manual Install](#manual-installation)
+    - [Install Dependencies](#install-dependencies)
+    - [Setup the Rails app](#setup-the-rails-app)
+    - [Add JavaScript](#add-javascript)
+    - [Run the server](#run-the-server)
+  - [Application Layout](#application-layout)
+  - [Advanced Use](#advanced-use)
+    - [Testing](#testing)
+    - [Interacting with the request and response in React code](#interacting-with-the-request-and-response-in-react-code)
+    - [Dealing with isomorphic state](#dealing-with-isomorphic-state)
+    - [Customizing the node server](#customizing-the-node-server)
+- [Performance tracking a React app](#performance-tracking-a-react-app)
+  - [Install dependencies](#install-dependencies)
+  - [Setup an endpoint for performance reports](setup-an-endpoint-for-performance-reports)
+  - [Add annotations](#add-annotations)
+  - [Send the report](#send-the-report)
+  - [Verify in development](#verify-in-development)
+  - [Configure StatsD for production](#configure-statsd-for-production)
+- [API](#api)
+  - [ReactRenderable](#reactrenderable)
+  - [PerformanceReportable](#performanceReportable)
+  - [Engine](#engine)
+  - [Generators](#generators)
+
+## Server-side-rendering
+
+### Alpha functionality - do not use in high-traffic production applications
+
+**Warning:** quilt_rails's server-side-rendering module `ReactRenderable` does not work at scale. Improvements to its architecture are being investigated. In its current state, it can be used for:
+
+- Workshop applications
+- Proof of concept applications
+- Low traffic applications
+
+For a description of the current architecture's problems, see [this Github comment](https://github.com/Shopify/quilt/issues/1059#issuecomment-539195340).
+
+The ["decide on a scalable quilt_rails architecture" issue](https://github.com/Shopify/quilt/issues/1100) will track discussion of future architectures.
+
+To scale up existing quilt_rails applications, skip server-side queries in your components. e.g.:
+
+```ts
+useQuery(MyQuery, {
+  skip: typeof document === 'undefined',
+});
+```
+
+### Quick start
 
 Using the magic of generators, we can spin up a basic app with a few console commands.
 
-### Generate Rails boilerplate
+#### Generate Rails boilerplate
 
 `dev init`
 
 When prompted, choose `rails`. This will generate a basic Rails application scaffold.
 
-### Add Ruby dependencies
+#### Add Ruby dependencies
 
 `bundle add sewing_kit quilt_rails`
 
 This will install our ruby dependencies and update the project's gemfile.
 
-### Generate Quilt boilerplate
+#### Generate Quilt boilerplate
 
 `rails generate quilt:install`
 
 This will install the Node dependencies, provide a basic React app (in TypeScript) and mounts the Quilt engine inside of `config/routes.rb`.
 
-### Try it out
+#### Try it out
 
 `dev server`
 
 Will run the application, starting up both servers and compiling assets.
 
-## Manual Installation
+### Manual installation
 
 An application can also be setup manually using the following steps.
 
-### Install Dependencies
+#### Install dependencies
 
 ```sh
 # Add core Node dependencies
@@ -70,11 +101,11 @@ yarn
 dev up
 ```
 
-### Setup the Rails app
+#### Setup the Rails app
 
 There are 2 ways to consume this package.
 
-#### Option 1: Mount the Engine
+##### Option 1: Mount the Engine
 
 Add the engine to `routes.rb`.
 
@@ -96,7 +127,7 @@ Rails.application.routes.draw do
 end
 ```
 
-#### Option 2: Add a React controller and routes
+##### Option 2: Add a React controller and routes
 
 Create a `ReactController` to handle react requests.
 
@@ -117,7 +148,7 @@ Add routes to default to the `ReactController`.
   root 'react#index'
 ```
 
-### Add JavaScript
+#### Add JavaScript
 
 `sewing_kit` looks for the top level component of your React app in `app/ui/index`. The component exported from this component (and any imported JS/CSS) will be built into a `main` bundle, and used to render the initial server-rendered markup.
 
@@ -135,15 +166,15 @@ function App() {
 export default App;
 ```
 
-### Run the server
+#### Run the server
 
 `dev server`
 
 Will run the application, starting up both servers and compiling assets.
 
-## Application layout
+### Application layout
 
-### Minimal
+#### Minimal
 
 The basic layout for an app using `quilt_rails` and friends will have a `ui` folder nested inside the normal Rails `app` folder, containing at _least_ an index.js file exporting a React component.
 
@@ -158,7 +189,7 @@ The basic layout for an app using `quilt_rails` and friends will have a `ui` fol
        └─- react_controller.rb (see above)
 ```
 
-### Rails and React
+#### Rails and React
 
 A more complex application will want a more complex layout. The following shows scalable locations for:
 
@@ -199,59 +230,9 @@ A more complex application will want a more complex layout. The following shows
                     └── Home.{js|ts}
 ```
 
-## API
-
-### ReactRenderable
-
-The `ReactRenderable` mixin is intended to be used in Rails controllers, and provides only the `render_react` method. This method handles proxying to a running `@shopify/react-server`.
-
-```ruby
-class ReactController < ApplicationController
-  include Quilt::ReactRenderable
-
-  def index
-    render_react
-  end
-end
-```
-
-### Engine
-
-`Quilt::Engine` provides a preconfigured controller which consumes `ReactRenderable` and provides an index route which uses it.
+### Advanced use
 
-```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  # ...
-  mount Quilt::Engine, at: '/path/to/react'
-end
-```
-
-### Configuration
-
-The `configure` method allows customization of the address the service will proxy to for UI rendering.
-
-```ruby
-  # config/initializers/quilt.rb
-  Quilt.configure do |config|
-    config.react_server_host = "localhost:3000"
-    config.react_server_protocol = 'https'
-  end
-```
-
-### Generators
-
-#### `quilt:install`
-
-Installs the Node dependencies, provide a basic React app (in TypeScript) and mounts the Quilt engine in `config/routes.rb`.
-
-#### `sewing_kit:install`
-
-Adds a basic `sewing-kit.config.ts` file.
-
-## Advanced use
-
-### Testing
+#### Testing
 
 For fast tests with consistent results, test front-end components using the tools provided by sewing-kit instead of Rails integration tests.
 
@@ -259,7 +240,7 @@ Use [`sewing-kit test`](https://github.com/Shopify/sewing-kit/blob/master/docs/c
 
 For testing React applications we provide and support [`@shopify/react-testing`](https://github.com/Shopify/quilt/tree/master/packages/react-testing).
 
-#### Example
+##### Example
 
 Given a component `MyComponent.tsx`
 
@@ -286,17 +267,17 @@ describe('MyComponent', () => {
 });
 ```
 
-#### Customizing the test environment
+##### Customizing the test environment
 
 Often you will want to hook up custom polyfills, global mocks, or other logic that needs to run either before the initialization of the test environment, or once for each test suite.
 
 By default, sewing-kit will look for such test setup files under `/app/ui/tests`. Check out the [documentation](https://github.com/Shopify/sewing-kit/blob/master/docs/plugins/jest.md#smart-defaults) for more details.
 
-### Interacting with the request and response in React code
+##### Interacting with the request and response in React code
 
 React-server sets up [@shopify/react-network](https://github.com/Shopify/quilt/blob/master/packages/react-network) automatically, so most interactions with the request or response can be done from inside the React app.
 
-#### Example: getting headers
+##### Example: getting headers
 
 ```tsx
 // app/ui/index.tsx
@@ -319,7 +300,7 @@ function App() {
 export default App;
 ```
 
-#### Example: redirecting
+##### Example: redirecting
 
 ```tsx
 // app/ui/index.tsx
@@ -337,13 +318,13 @@ function App() {
 export default App;
 ```
 
-### Isomorphic state
+#### Isomorphic state
 
 With SSR enabled React apps, state must be serialized on the server and deserialized on the client to keep it consistent. When using `@shopify/react-server`, the best tool for this job is [`@shopify/react-html`](https://github.com/Shopify/quilt/tree/master/packages/react-html)'s [`useSerialized`](https://github.com/Shopify/quilt/tree/master/packages/react-html#in-your-application-code) hook.
 
 `useSerialized` can be used to implement [universal-providers](https://github.com/Shopify/quilt/tree/master/packages/react-universal-provider#what-is-a-universal-provider-), allowing application code to manage what is persisted between the server and client without adding any custom code to client or server entrypoints. We offer some for common use cases such as [CSRF](https://github.com/Shopify/quilt/tree/master/packages/react-csrf-universal-provider), [GraphQL](https://github.com/Shopify/quilt/tree/master/packages/react-graphql-universal-provider), [I18n](https://github.com/Shopify/quilt/tree/master/packages/react-i18n-universal-provider), and the [Shopify App Bridge](https://github.com/Shopify/quilt/tree/master/packages/react-app-bridge-universal-provider).
 
-### Customizing the node server
+#### Customizing the node server
 
 By default, sewing-kit bundles in `@shopify/react-server-webpack-plugin` for `quilt_rails` applications to get apps up and running fast without needing to manually write any node server code. If what it provides is not sufficient, a custom server can be defined by adding a `server.js` or `server.ts` file to the app folder.
 
@@ -380,7 +361,7 @@ const app = createServer({
 export default app;
 ```
 
-### Fixing rejected CSRF tokens for new user sessions
+#### Fixing rejected CSRF tokens for new user sessions
 
 If a React component calls back to a Rails endpoint (e.g., `/graphql`), Rails may throw a `Can't verify CSRF token authenticity` exception. This stems from the Rails CSRF tokens not persisting until after the first `UiController` call ends.
 
@@ -404,3 +385,336 @@ class GraphqlController < ApplicationController
   end
 end
 ```
+
+## Performance tracking a React app
+
+Using [`Quilt::Performance::Reportable`](#performanceReportable) and [@shopify/react-performance](https://www.npmjs.com/package/@shopify/react-performance) it's easy to add performance tracking to apps using[`sewing_kit`](https://www.npmjs.com/package/@shopify/sewing-kit) for client-side-rendering or `quilt_rails` for server-side-rendering.
+
+### Install dependencies
+
+1. Install the gem (if your app is not already using `quilt_rails`).
+
+```bash
+bundle add quilt_rails
+```
+
+2. Install `@shopify/react-performance`, the library we will use to annotate our React application and send performance reports to our server.
+
+```bash
+yarn add @shopify/react-performance
+```
+
+### Setup an endpoint for performance reports
+
+If your application is not using `Quilt::Engine`, you will need to manually configure the server-side portion of performance tracking. If it _is_ using the engine, the following will be done automatically.
+
+1. Add a `PerformanceController` and the corresponding routes to your Rails app.
+
+```ruby
+# app/controllers/performance_report_controller.rb
+
+class PerformanceReportController < ActionController::Base
+  include Quilt::Performance::Reportable
+  protect_from_forgery with: :null_session
+
+  def create
+    process_report
+
+    render json: { result: 'success' }, status: 200
+  rescue ActionController::ParameterMissing => error
+    render json: { error: error.message, status: 422 }
+  end
+end
+```
+
+2. Add a route pointing at the controller.
+
+```ruby
+# config/routes.rb
+
+post '/performance_report', to: 'performance_report#create'
+
+# rest of routes
+```
+
+### Add annotations
+
+Add a [`<PerformanceMark />`](https://github.com/Shopify/quilt/tree/master/packages/react-performance#performancemark) to each of your route-level components.
+
+```tsx
+// app/ui/features/Home/Home.tsx
+import {PerformanceMark} from '@shopify/react-performance';
+
+export function Home() {
+  return (
+    <div>
+      My Cool Home Page
+      {/* tell the library the page has finished rendering completely */}
+      <PerformanceMark stage="complete" id="Home" />
+    </div>
+  );
+}
+```
+
+### Send the report
+
+Add a [`usePerformanceReport`](https://github.com/Shopify/quilt/tree/master/packages/react-performance#usePerformanceReport) call to your top-level `<App />` component.
+
+```tsx
+// app/ui/foundation/App/App.tsx
+import {usePerformanceReport} from '@shopify/react-performance';
+
+export function App() {
+  // send the report to the server
+  usePerformanceReport('/performance_report');
+
+  return <>{/* your app JSX goes here*/}</>;
+}
+```
+
+For more details on how to use the APIs from `@shopify/react-performance` check out its [documentation](https://github.com/Shopify/quilt/tree/master/packages/react-performance).
+
+### Verify in development
+
+By default `quilt_rails` will not send metrics in development mode. To verify your app is setup correctly you can check in your network tab when visiting your application and see that POST requests are sent to `/performance_report`, and recieve a `200 OK` response.
+
+If you want more insight into what distributions _would_ be sent in production, you can use the `on_distribution` callback provided by the library to setup logging.
+
+```ruby
+# app/controllers/performance_report_controller.rb
+
+class PerformanceReportController < ActionController::Base
+  include Quilt::Performance::Reportable
+  protect_from_forgery with: :null_session
+
+  def create
+    # customize process_report's behaviour with a block
+    process_report do |client|
+      client.on_distribution do |name, value, tags|
+        # We log out the details of each distribution that would be sent in production.
+        Rails.logger.debug("Distribution: #{name}, #{value}, #{tags}")
+      end
+    end
+
+    render json: { result: 'success' }, status: 200
+  rescue ActionController::ParameterMissing => error
+    render json: { error: error.message, status: 422 }
+  end
+end
+```
+
+Now you can check your Rails console output and verify that metrics are reported as expected.
+
+### Configure StatsD for production
+
+> Attention Shopifolk! If using `dev` your `StatsD` endpoint will already be configured for you in production. You should not need to do the following. ✨
+
+To tell `Quilt::Performance::Reportable` where to send it's distributions, setup the environment variables detailed [documentation](https://github.com/Shopify/statsd-instrument#configuration).
+
+## API
+
+### ReactRenderable
+
+The `ReactRenderable` mixin is intended to be used in Rails controllers, and provides only the `render_react` method. This method handles proxying to a running `@shopify/react-server`.
+
+```ruby
+class ReactController < ApplicationController
+  include Quilt::ReactRenderable
+
+  def index
+    render_react
+  end
+end
+```
+
+### Performance
+
+#### Reportable
+
+The `Quilt::Performance::Reportable` mixin is intended to be used in Rails controllers, and provides only the `process_report` method. This method handles parsing an incoming report from [@shopify/react-performance's](https://www.npmjs.com/package/@shopify/react-performance) `<PerformanceReport />` component (or a custom report in the same format) and sending it to your application's StatsD endpoint as `distribution`s using [`StatsD-Instrument`](https://rubygems.org/gems/statsd-instrument).
+
+> **Note** `Quilt::Performance::Reportable` does not require you to use the `React::Renderable` mixin, React-Server, or even any server-side-rendering solution at all. It should work perfectly fine for applications using something like `sewing_kit_script_tag` based client-side-rendering.
+
+```ruby
+class PerformanceController < ApplicationController
+  include Quilt::Performance::Reportable
+
+  def create
+    process_report
+  end
+end
+```
+
+The params sent to the controller are expected to be of type `application/json`. Given the following example JSON sent by `@shopify/react-performance`,
+
+```json
+{
+  "connection": {
+    "rtt": 100,
+    "downlink": 2,
+    "effectiveType": "3g",
+    "type": "4g"
+  },
+  "navigations": [
+    {
+      "details": {
+        "start": 12312312,
+        "duration": 23924,
+        "target": "/",
+        "events": [
+          {
+            "type": "script",
+            "start": 23123,
+            "duration": 124
+          },
+          {
+            "type": "style",
+            "start": 23,
+            "duration": 14
+          }
+        ],
+        "result": 0
+      },
+      "metadata": {
+        "index": 0,
+        "supportsDetailedTime": true,
+        "supportsDetailedEvents": true
+      }
+    }
+  ],
+  "events": [
+    {
+      "type": "ttfb",
+      "start": 2,
+      "duration": 1000
+    }
+  ]
+}
+```
+
+the above controller would send the following metrics:
+
+```ruby
+StatsD.distribution('time_to_first_byte', 2, ['browser_connection_type:3g'])
+StatsD.distribution('time_to_first_byte', 2, ['browser_connection_type:3g'])
+StatsD.distribution('navigation_complete', 23924, ['browser_connection_type:3g'])
+StatsD.distribution('navigation_usable', 23924, ['browser_connection_type:3g'])
+```
+
+##### Customizing `process_report` with a block
+
+The behaviour of `process_report` can be customized by manipulating the `Quilt::Performance::Client` instance yielded into its implicit block parameter.
+
+```ruby
+process_report do |client|
+  # client.on_distribution do ....
+end
+```
+
+#### Client
+
+The `Quilt::Performance::Client` class is yielded into the block parameter for `process_report`, and is the primary API for customizing what metrics are sent for a given POST.
+
+##### Client#on_distribution
+
+The `on_distribution` method takes a block which is run for each distribution (including custom ones) sent during `process_report`.
+
+The provided callback can be used to easily add logging or other side-effects to your measurements.
+
+```ruby
+client.on_distribution do |metric_name, value, tags|
+  Rails.logger.debug "#{metric_name}: #{value}, tags: #{tags}"
+end
+```
+
+##### Client#on_navigation
+
+The `on_navigation` method takes a block which is run once per navigation reported to the performance controller _before_ the default distributions for the navigation are sent.
+
+The provided callback can be used to add tags to the default `distributions` for a given navigation.
+
+```ruby
+client.on_navigation do |navigation, tags|
+  # add tags to be sent with each distribution for this navigation
+  tags[:connection_rtt] = navigation.connection.rtt
+  tags[:connection_type] = navigation.connection.type
+  tags[:navigation_target] = navigation.target
+end
+```
+
+It can also be used to compute and send entirely custom metrics.
+
+```ruby
+client.on_navigation do |navigation, tags|
+  # calculate and then send an additional distribution
+  weight = navigation.events_with_size.reduce(0) do |total, event|
+    total + event.size
+  end
+  client.distribution('navigation_total_resource_weight', weight, tags)
+end
+```
+
+##### Client#on_event
+
+The `on_event` method takes a block which is run once per event reported to the performance controller _before_ the default distributions for the event are sent.
+
+The provided callback can be used to add tags to the default `distributions` for a given event, or perform other side-effects.
+
+```ruby
+client.on_event do |event, tags|
+  # add tags to be sent with each distribution for this event
+  tags[:connection_rtt] = event.connection.rtt
+  tags[:connection_type] = event.connection.type
+end
+```
+
+### Engine
+
+`Quilt::Engine` provides:
+
+- a preconfigured `UiController` which consumes `ReactRenderable`
+- a preconfigured `PerformanceReportController` which consumes `Performance::Reportable`
+- a `/performance_report` route mapped to `performance_report#index`
+- a catch-all index route mapped to the `UiController#index`
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # ...
+  mount Quilt::Engine, at: '/my-front-end'
+end
+```
+
+The above is the equivalent of
+
+```ruby
+  post '/my-front-end/performance_report', to: 'performance_report#create'
+  get '/my-front-end/*path', to: 'ui#index'
+  get '/my-front-end', to: 'ui#index'
+```
+
+### Configuration
+
+The `configure` method allows customization of the address the service will proxy to for UI rendering.
+
+```ruby
+  # config/initializers/quilt.rb
+  Quilt.configure do |config|
+    config.react_server_host = "localhost:3000"
+    config.react_server_protocol = 'https'
+  end
+```
+
+### StatsD environment variables
+
+The `Performance::Reportable` mixin uses [https://github.com/Shopify/statsd-instrument](StatsD-Instrument) to send distributions. For detailed instructions on configuring where it sends data see [the documentation](https://github.com/Shopify/statsd-instrument#configuration).
+
+### Generators
+
+#### `quilt:install`
+
+Installs the Node dependencies, provide a basic React app (in TypeScript) and mounts the Quilt engine in `config/routes.rb`.
+
+#### `sewing_kit:install`
+
+Adds a basic `sewing-kit.config.ts` file.

data/app/controllers/quilt/performance_report_controller.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Quilt
+  class PerformanceReportController < ActionController::Base
+    include Quilt::Performance::Reportable
+    protect_from_forgery with: :null_session
+
+    def create
+      process_report
+
+      render json: { result: 'success' }, status: 200
+    rescue ActionController::ParameterMissing => error
+      render json: { error: error.message, status: 422 }
+    end
+  end
+end

data/config/routes.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 Quilt::Engine.routes.draw do
+  post '/performance_report', to: 'performance_report#create'
   get '/*path', to: 'ui#index'
   root 'ui#index'
 end

data/lib/quilt_rails.rb

@@ -7,5 +7,6 @@ require "quilt_rails/engine"
 require "quilt_rails/logger"
 require "quilt_rails/configuration"
 require "quilt_rails/react_renderable"
+require "quilt_rails/performance"
 require "quilt_rails/trusted_ui_server_csrf_strategy"
 require "quilt_rails/monkey_patches/active_support_reloader" if Rails.env.development?

data/lib/quilt_rails/configuration.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module Quilt
   class Configuration
     attr_accessor :react_server_host, :react_server_protocol

data/lib/quilt_rails/performance.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "quilt_rails/performance/event_metadata"
+require "quilt_rails/performance/event"
+require "quilt_rails/performance/connection"
+require "quilt_rails/performance/navigation_metadata"
+require "quilt_rails/performance/navigation"
+require "quilt_rails/performance/report"
+require "quilt_rails/performance/client"
+require "quilt_rails/performance/reportable"
+
+module Quilt
+  module Performance
+    LIFECYCLE = {
+      time_to_first_byte: 'time_to_first_byte',
+      time_to_first_contentful_paint: 'time_to_first_contentful_paint',
+      time_to_first_paint: 'time_to_first_paint',
+      dom_content_loaded: 'dom_content_loaded',
+      first_input_delay: 'first_input_delay',
+      load: 'dom_load',
+    }
+
+    NAVIGATION = {
+      complete: 'navigation_complete',
+      usable: 'navigation_usable',
+      download_size: 'navigation_download_size',
+      cache_effectiveness: 'navigation_cache_effectiveness',
+    }
+  end
+end

data/lib/quilt_rails/performance/client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Quilt
+  module Performance
+    class Client
+      def initialize(report)
+        @report = report
+        @base_tags = {
+          browser_connection_type: report.connection.effective_type,
+        }.freeze
+
+        @distribution_callback = proc { |_name, _value, _tags| nil }
+        @event_callback = proc { |_event, _tags| {} }
+        @navigation_callback = proc { |_navigation, _tags| {} }
+      end
+
+      def self.send!(report)
+        client = Client.new(report)
+
+        # Allow the user to customize things
+        if block_given?
+          yield(client)
+        end
+
+        client.send(:process_report!)
+      end
+
+      def distribution(metric_name, value, tag_hash = {})
+        tags = tag_hash.map { |key, hash_value| "#{key}:#{hash_value}" }
+
+        @distribution_callback.call(metric_name, value, tags)
+        StatsD.distribution(metric_name, value, tags) unless Rails.env.dev?
+      end
+
+      def on_navigation(&block)
+        @navigation_callback = block
+      end
+
+      def on_event(&block)
+        @event_callback = block
+      end
+
+      def on_distribution(&block)
+        @distribution_callback = block
+      end
+
+      private
+
+      def process_report!
+        report_events
+        report_navigations
+      end
+
+      def report_events
+        @report.events.each do |event|
+          event_tags = @base_tags.dup
+          @event_callback.call(event, event_tags)
+
+          distribution(event.metric_name, event.value, event_tags)
+        end
+      end
+
+      def report_navigations
+        @report.navigations.each do |navigation|
+          tags = @base_tags.dup
+          @navigation_callback.call(navigation, tags)
+          send_default_navigation_distributions(navigation, tags)
+          send_conditional_navigation_distributions(navigation, tags)
+        end
+      end
+
+      def send_default_navigation_distributions(navigation, tags)
+        distribution(NAVIGATION[:complete], navigation.time_to_complete, tags)
+        distribution(NAVIGATION[:usable], navigation.time_to_usable, tags)
+      end
+
+      def send_conditional_navigation_distributions(navigation, tags)
+        size = navigation.total_download_size
+        distribution(NAVIGATION[:download_size], size, tags) unless size.nil?
+
+        effectiveness = navigation.cache_effectiveness
+        distribution(NAVIGATION[:cache_effectiveness], effectiveness, tags) unless effectiveness.nil?
+      end
+    end
+  end
+end

data/lib/quilt_rails/performance/connection.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Quilt
+  module Performance
+    class Connection
+      attr_accessor :downlink
+      attr_accessor :effective_type
+      attr_accessor :rtt
+      attr_accessor :type
+
+      def self.from_params(params)
+        params.transform_keys! { |key| key.underscore.to_sym }
+
+        Connection.new(
+          downlink: params[:downlink],
+          effective_type: params[:effective_type],
+          rtt: params[:rtt],
+          type: params[:type]
+        )
+      end
+
+      def initialize(downlink:, effective_type:, rtt:, type:)
+        @downlink = downlink
+        @effective_type = effective_type
+        @rtt = rtt
+        @type = type
+      end
+    end
+  end
+end

data/lib/quilt_rails/performance/event.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Quilt
+  module Performance
+    class Event
+      TYPE = {
+        time_to_first_byte: 'ttfb',
+        time_to_first_paint: 'ttfp',
+        time_to_first_contentful_paint: 'ttfcp',
+        dom_content_loaded: 'dcl',
+        first_input_delay: 'fid',
+        load: 'load',
+        long_task: 'longtask',
+        usable: 'usable',
+        graphql: 'graphql',
+        script_download: 'script',
+        style_download: 'style',
+      }
+
+      attr_accessor :type
+      attr_accessor :start
+      attr_accessor :duration
+      attr_accessor :metadata
+      attr_accessor :connection
+
+      def self.from_params(params)
+        params.require([:type, :start, :duration])
+
+        attributes = {
+          type: params[:type],
+          start: params[:start],
+          duration: params[:duration],
+          metadata: nil,
+        }
+
+        if params[:metadata]
+          attributes[:metadata] = EventMetadata.from_params(params[:metadata])
+        end
+
+        Event.new(**attributes)
+      end
+
+      def initialize(type:, start:, duration:, metadata:)
+        @type = type
+        @start = start
+        @duration = duration
+        @metadata = metadata
+      end
+
+      def value
+        raw_value = if type == TYPE[:first_input_delay]
+          duration
+        else
+          start
+        end
+
+        raw_value.round
+      end
+
+      def metric_name
+        type_name = TYPE.key(type)
+        if LIFECYCLE[type_name].nil?
+          type
+        else
+          LIFECYCLE[type_name]
+        end
+      end
+
+      def has_metadata?
+        !metadata.nil?
+      end
+    end
+  end
+end

data/lib/quilt_rails/performance/event_metadata.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Quilt
+  module Performance
+    class EventMetadata
+      attr_accessor :name
+      attr_accessor :size
+
+      def self.from_params(params)
+        EventMetadata.new(
+          name: params[:name],
+          size: params[:size],
+        )
+      end
+
+      def initialize(name:, size:)
+        @name = name
+        @size = size
+      end
+
+      def has_size?
+        !size.nil?
+      end
+    end
+  end
+end

data/lib/quilt_rails/performance/navigation.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Quilt
+  module Performance
+    class Navigation
+      attr_accessor :start
+      attr_accessor :time_to_complete
+      attr_accessor :target
+      attr_accessor :events
+      attr_accessor :result
+      attr_accessor :metadata
+      attr_accessor :connection
+
+      def self.from_params(params)
+        params.transform_keys! { |key| key.underscore.to_sym }
+        params.require(:details)
+
+        attributes = {
+          start: params[:details][:start],
+          time_to_complete: params[:details][:duration],
+          target: params[:details][:target],
+          result: params[:details][:result],
+          events: (params[:details][:events] || []).map do |event|
+            Event.from_params(event)
+          end,
+          metadata: NavigationMetadata.from_params(params[:metadata] || {}),
+        }
+
+        Navigation.new(**attributes)
+      end
+
+      def initialize(
+        start:,
+        time_to_complete:,
+        target:,
+        result:,
+        events: [],
+        metadata: {}
+      )
+        @start = start
+        @time_to_complete = time_to_complete
+        @target = target
+        @result = result
+        @events = events
+        @metadata = metadata
+      end
+
+      def events_by_type(target_type)
+        events.select do |event|
+          event.type == target_type
+        end
+      end
+
+      def resource_events
+        style_events = events_by_type(Event::TYPE[:style_download])
+        script_events = events_by_type(Event::TYPE[:script_download])
+        style_events.concat(script_events)
+      end
+
+      def events_with_size
+        resource_events.select do |event|
+          event.has_metadata? && event.metadata.has_size?
+        end
+      end
+
+      def time_to_usable
+        usable_event = events_by_type(Event::TYPE[:usable]).first
+        return usable_event.start - start unless usable_event.nil?
+
+        time_to_complete
+      end
+
+      def total_download_size
+        events_with_size.reduce(nil) do |total, current|
+          current_size = current.metadata.size
+          return current_size + total unless total.nil?
+          current_size
+        end
+      end
+
+      def total_duration_by_event_type(type)
+        events = events_by_type(type)
+
+        events.reduce(0) do |total, current_event|
+          total + (current_event.duration || 0)
+        end
+      end
+
+      def cache_effectiveness
+        events = events_with_size
+
+        if events.empty? || events.any? { |event| event.metadata.size.nil? }
+          return nil
+        end
+
+        cached_events = events.select do |event|
+          # this is not actually checking the size of an array,
+          # there is no EventMetadata#any? method, so this check is being tripped erroneously.
+          # rubocop:disable Style/ZeroLengthPredicate
+          event.metadata.size == 0
+          # rubocop:enable
+        end
+        cached_events.length / events.length
+      end
+    end
+  end
+end

data/lib/quilt_rails/performance/navigation_metadata.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Quilt
+  module Performance
+    class NavigationMetadata
+      attr_accessor :index
+      attr_accessor :supports_detailed_time
+      attr_accessor :supports_detailed_events
+
+      def self.from_params(params = {})
+        NavigationMetadata.new(
+          index: params[:index],
+          supports_detailed_time: params[:supports_detailed_time],
+          supports_detailed_events: params[:supports_detailed_events],
+        )
+      end
+
+      def initialize(index:, supports_detailed_events:, supports_detailed_time:)
+        @index = index
+        @supports_detailed_time = supports_detailed_time
+        @supports_detailed_events = supports_detailed_events
+      end
+
+      def has_size?
+        !size.nil?
+      end
+    end
+  end
+end

data/lib/quilt_rails/performance/report.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Quilt
+  module Performance
+    class Report
+      attr_accessor :events
+      attr_accessor :navigations
+      attr_accessor :connection
+
+      def self.from_params(params)
+        params.transform_keys! { |key| key.underscore.to_sym }
+        params.require(:connection)
+
+        connection = Connection.from_params(params[:connection])
+
+        Report.new(
+          connection: connection,
+          navigations: (params[:navigations] || []).map do |navigation|
+            navigation = Navigation.from_params(navigation)
+            navigation.connection = connection
+            navigation
+          end,
+          events: (params[:events] || []).map do |event|
+            event = Event.from_params(event)
+            event.connection = connection
+            event
+          end,
+        )
+      end
+
+      def initialize(events:, navigations:, connection:)
+        @events = events
+        @navigations = navigations
+        @connection = connection
+      end
+    end
+  end
+end

data/lib/quilt_rails/performance/reportable.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Quilt
+  module Performance
+    module Reportable
+      def process_report(&block)
+        params.transform_keys! { |key| key.underscore.to_sym }
+        Client.send!(Report.from_params(params), &block)
+      end
+    end
+  end
+end

data/lib/quilt_rails/react_renderable.rb

@@ -47,12 +47,15 @@ module Quilt
       def initialize(url)
         # rubocop:disable LineLength
         super "Errno::ECONNREFUSED: Waiting for React server to boot up. If this error presists verify that @shopify/react-server is configured on #{url}"
+        # rubocop:enable LineLength
       end
     end
 
     class DoNotIntegrationTestError < StandardError
       def initialize
+        # rubocop:disable LineLength
         super "Do not try to use Rails integration tests on your quilt_rails app. Instead use Jest and @shopify/react-testing to test your React application directly."
+        # rubocop:enable LineLength
       end
     end
   end

data/lib/quilt_rails/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Quilt
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quilt_rails
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Mathew Allen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-25 00:00:00.000000000 Z
+date: 2019-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: statsd-instrument
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.7.0
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -76,6 +90,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - Rakefile
+- app/controllers/quilt/performance_report_controller.rb
 - app/controllers/quilt/ui_controller.rb
 - config/routes.rb
 - lib/generators/quilt/USAGE
@@ -91,6 +106,15 @@ files:
 - lib/quilt_rails/engine.rb
 - lib/quilt_rails/logger.rb
 - lib/quilt_rails/monkey_patches/active_support_reloader.rb
+- lib/quilt_rails/performance.rb
+- lib/quilt_rails/performance/client.rb
+- lib/quilt_rails/performance/connection.rb
+- lib/quilt_rails/performance/event.rb
+- lib/quilt_rails/performance/event_metadata.rb
+- lib/quilt_rails/performance/navigation.rb
+- lib/quilt_rails/performance/navigation_metadata.rb
+- lib/quilt_rails/performance/report.rb
+- lib/quilt_rails/performance/reportable.rb
 - lib/quilt_rails/react_renderable.rb
 - lib/quilt_rails/trusted_ui_server_csrf_strategy.rb
 - lib/quilt_rails/version.rb