mission_control-web 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55a15e8774db77d237cc2774713fffddc56311462282805c723ed49c3f2514c8
-  data.tar.gz: 220c96b20fdde502187c4e88099c8713ee1394413ab8e6d0540ad2069b6942fd
+  metadata.gz: 263fd9deb28663f3a334c57d836127d45e9acfb9c2c7cb542659715ce23bcef2
+  data.tar.gz: 38867c05c69375966ae4512fe39ea7769938843c043776c23b4b2d52ba1490b9
 SHA512:
-  metadata.gz: 8acd06b3debdca5db4cfc6d22ee6c4d6d2df6f7091ffcb865503d38835a8e832d52711a87e5179c2ae2535a6cab17594e320d57c7c1a972d854fc8927cfb5857
-  data.tar.gz: c4260b3d1ddaf75e1a92aaf592adbe32e2a2f76f6df1341395daad2e719044012cdfc239076228aa4d72ed7b0ebd7a8b1aa1b0e821c91994bbd2502809a5fc01
+  metadata.gz: '08dfb3c27a1acc73a75be00ed3331412451913692fcefa539f2da96ee1a821b2959abdf21927193d0a3b16fc5a3a090fc9c281271cf578f1c69a4b522dcdf8b7'
+  data.tar.gz: dae3c2f2ff15c3b39e5a640cc0486a090557bf36c2bcfeb119e1eea45cc34bffc996a06ede592be861435a1daf00170351389b776637f608e17862b00b5a1b75

data/MIT-LICENSE

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

data/README.md

@@ -1,34 +1,141 @@
-# MissionControl::Web
+# Mission Control - Web
 
-TODO: Delete this and the text below, and describe your gem
+This gem provides a Rails-based frontend and middleware to deny access to particular parts of your application. This is
+especially useful in an incident response scenario such as deployment of unperformant code, or a denial of service
+attack.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/mission_control/web`. To experiment with that code, run `bin/console` for an interactive prompt.
+<img width="952" alt="Screenshot of Mission Control - Web admin UI" src="https://github.com/basecamp/mission_control-web/assets/1773614/5c75a304-820e-4151-882e-f0782211356c">
+
+## How it works
+
+Mission Control - Web can be configured via the admin interface to block requests whose path matched a regex pattern. If
+the requested path matches any "Denied" path, it will be blocked with a 503 HTTP status code.
+
+## Usage
+
+You can choose to deploy Mission Control - Web admin and middleware both in the same Rails app, or two separate apps, a
+protected Rails app and an admin app.
+
+The benefit of using two separate apps is that if your protected app is attacked or suffers a performance issue, it may
+become inaccessible while an admin app does not.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's Gemfile:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem "mission_control-web"
+```
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+And then execute:
+```bash
+$ bundle
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+then, follow the instructions below for a single app, or a separate admin app.
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## Installation in a single app
 
-## Usage
+And then execute:
+```bash
+$ bin/rails generate mission_control:web:install
+```
+
+## Installation with two apps, admin and protected
+
+After adding the `mission_control-web` gem, in your admin app:
+
+```bash
+$ bin/rails generate mission_control:web:install:admin
+```
+
+and in your protected Rails app:
+
+```bash
+$ bin/rails generate mission_control:web:install:middleware
+```
+
+## Configuration
+
+### Redis client
+
+Configure Mission Control - Web with a Redis client.
+
+```rb
+# config/initializers/mission_control_web.rb
+
+config.mission_control.web.redis = Redis.new(url: "redis://server:6379/0")
+```
+
+### Administered applications
+
+```rb
+config.mission_control.web.administered_applications = [ { name: "My Rails App", redis: Redis.new(url: "redis://server:6379/0") } ]
+```
+
+### Authentication and base controller class
+
+By default, Mission Control's controllers will extend the host app's ApplicationController. If no authentication is
+enforced, the admin pages will be available to everyone. You might want to implement some kind of authentication for
+this in your app. To make this easier, you can specify a different controller as the base class for Mission Control's
+controllers:
+
+```rb
+config.mission_control.web.base_controller_class = "AdminController"
+```
+
+### Custom "denied" page
+
+You can configure a custom page to show to users when a request is denied by Mission Control - Web. Configure this like
+so:
+
+```rb
+config.mission_control.web.errors_controller = MissionControl::Web::CustomErrorsController
+```
+
+Then, in your application, create a custom errors controller:
+
+```rb
+class MissionControl::Web::CustomErrorsController < MissionControl::Web::ErrorsController
+  def disallowed
+    render file: "public/503.html"
+  end
+end
+```
+
+### Other configuration
+
+Useful for disabling the Mission Control - Web request intercept middleware on a per-application or per-environment basis:
+
+```rb
+config.mission_control.web.middleware_enabled = false
+```
+
+Denied paths are cached by the middleware and refreshed from Redis on this interval. With this configuration, it takes up to 10 seconds for path denial to take effect:
+
+```rb
+config.mission_control.web.routes_cache_ttl = 10.seconds
+```
+
+## Testing
+
+Run:
 
-TODO: Write usage instructions here
+```sh
+rake test
+```
 
-## Development
+Performance tests can be run in the "profile" environment for more consistent results with:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```sh
+RAILS_ENV=profile rake test:performance
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Resiliency
 
-## Contributing
+If Redis is down (or raises any instance of Redis::BaseConnectionError), Mission Control Web middleware will fail-open.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/mission_control-web.
+It's recommended to also consider using a resilient Redis client with a circuit-breaker. See [Semian](https://github.com/Shopify/semian).
 
 ## License
 

data/Rakefile

@@ -1,8 +1,26 @@
-# frozen_string_literal: true
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
 
 require "bundler/gem_tasks"
-require "minitest/test_task"
 
-Minitest::TestTask.create
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"].exclude("test/performance/**/*")
+  t.verbose = false
+end
+
+namespace :test do
+  Rake::TestTask.new(:performance) do |t|
+    t.libs << "test"
+    t.test_files = FileList["test/performance/**/*_test.rb"]
+    t.verbose = false
+  end
+end
 
 task default: :test

data/app/assets/config/mission_control_web_manifest.js

@@ -0,0 +1,2 @@
+//= link_directory ../stylesheets/mission_control/web .css
+//= link_directory ../../javascript/mission_control/web .js

data/app/assets/stylesheets/mission_control/web/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */