light_switch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 675a8f2ae1d5eb4e4beb9afdf243d5bec721eb4a7c3c520353ab74ea3dae8afc
+  data.tar.gz: 9df76f5c003d099f5b5bb186c8a931048bd1dcf484d906df252c9ca133820f97
+SHA512:
+  metadata.gz: 6ac3c7df6e5330247760c3b0ee8aafd96332553d4e0eb7d25ab8577f16b1f2fbcef9d8b9c5299d7fb0be1be37fa73464b6215e13e45511f238ad1acd06a8a73e
+  data.tar.gz: 74295e949fbdc54ec2c73a19137eecc853415fe66d347f65056f1462882cb6bcbc7ecdc069f6f2dc587601992342b644b0bcf514df459f387483c98fc3cadb64

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,209 @@
+# LightSwitch
+
+Simple circuit breakers on Rails
+
+## Use Cases
+
+`LightSwitch` aims to be a very simple circuit breaker implementation. You can
+use a `LightSwitch` to turn things on and to turn things off. That's pretty much
+it.
+
+[Stoplight](https://github.com/bolshakov/stoplight) and
+[Circuitbox](https://github.com/yammer/circuitbox) are excellent, full-featured
+[circuit breaker](https://martinfowler.com/bliki/CircuitBreaker.html) libraries.
+[Semian](https://github.com/Shopify/semian) is an even more sophisticated beast.
+`LightSwitch` is much more basic. In particular, `LightSwitch` does not
+dynamically respond and adjust to errors. As the operator of your application,
+you are expected to manually turn switches off and on when you need to.
+
+You may ask, "If I have turned off a particular piece of code, how do I know
+when it's okay to turn it back on?"  That's a great question but it's not one
+that `LightSwitch` tries to answer for you. `Stoplight` and `Circuitbox` are
+great at that sort of circuit breaking.  Maybe you are monitoring a third-party's
+status page. Maybe another team is fixing their service and will let you know
+when the service is back up. Maybe you just turn your piece of code back on and
+monitor things closely.
+
+Some apps may not need the sophisticated, powerful behavior of `Stoplight` or
+`Circuitbox`; some apps may not run their recommended infrastructure (e.g. Redis).
+For simple cases where you are already running Rails, you may prefer the
+simplicity of `LightSwitch`.
+
+### LightSwitch vs. Flipper
+
+`LightSwitch` imitates [Flipper](https://github.com/flippercloud/flipper) when
+it comes to its API.  If you want to use `Flipper` for your circuit breaking
+needs, go for it.  Some teams prefer to reserve `Flipper` strictly for feature
+flags.  Some organizations expose the Flipper UI to a wide range of internal
+users especially if Product Managers enable and disable features on behalf of
+customers.  You probably want to limit the exposure of your `LightSwitches`.  You
+would not want someone to turn off a piece of code unless they really knew what
+they were doing.  `LightSwitch` can give you a little separation between feature
+flags and circuit breakers.  `Flipper` is well-suited to do the job if you want
+to use it, though.
+
+## Usage
+
+A `LightSwitch::Switch` has two states, `on` and `off`. This gem's convention
+is that an `off` switch will short circuit a given piece of code.  Therefore
+the recommended usage of `LightSwitch` is something like this:
+```ruby
+def my_method
+  return if LightSwitch.off?(:my_switch)
+
+  do_stuff
+end
+```
+
+Or
+
+```ruby
+def my_method
+  do_stuff if LightSwitch.on?(:my_switch)
+end
+```
+
+You can interpret `off` and `on` however you want; it's up to you.
+What few defaults `LightSwitch` implements assume the convention above, though.
+
+### Operating Switches
+
+If you have Rails console access, you can turn switches on and off:
+
+```ruby
+LightSwitch[:my_switch].on!  # turns the switch on
+LightSwitch[:my_switch].off! # turns the switch off
+```
+
+### LightSwitch UI
+
+LightSwitch comes with a web UI that can be mounted in your rails application.
+
+![UI](docs/light_switch_ui.png)
+
+Just add the following to `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount LightSwitch::Engine => "/light_switch"
+end
+```
+
+You can limit access to the UI by using
+[Rails routing constraints](https://guides.rubyonrails.org/routing.html#advanced-constraints).
+
+### Configuration
+
+You most likely want to initialize all of your switches when your app boots up.
+This ensures that the switches are present in the LightSwitch UI so that you
+can easily manage them. If you forget to initialize a switch, `LightSwitch` will
+assume that the switch is `on` so that your code guarded by a switch will run
+(assuming you follow the conventions demonstrated above). You can initialize
+your switches in a Rails initializer.
+
+```ruby
+# config/initializers/light_switch.rb
+
+LightSwitch.configure do |config|
+  config.switches = %i[
+    one_switch
+    two_switch
+    red_switch
+    blue_switch
+  ]
+end
+```
+
+### Caching
+
+By default, `LightSwitch` does not leverage caching, but you can configure
+`LightSwitch` to use a cache if you have performance concerns. For example,
+`Rails.cache` may be configured by setting `LightSwitch.config.cache` in a
+Rails initializer:
+
+```ruby
+# config/initializers/light_switch.rb
+
+LightSwitch.configure do |config|
+  config.cache = Rails.cache
+
+  # You can also provide options that will be used in calls to cache.fetch.
+  # The default cache_fetch_options are:
+  config.cache_fetch_options = { expires_in: 1.day, race_condition_ttl: 5.minutes }
+end
+```
+
+`LightSwitch` resets cached values whenever an underlying `LightSwitch::Switch`
+model is changed.  You should **not** use an in-memory cache for `LightSwitch`.
+If you are using an in-memory cache, `LightSwitch` has no way to clear the caches
+used by all of the various processes running your application (web workers, Sidekiq workers, etc.).
+If you are using a centralized cache, like Redis or MemCached, feel free to use
+it with `LightSwitch`.  The queries to read a switch from the database are
+indexed and will return very quickly, so most `LightSwitch` users will not
+need caching.
+
+You can also implement your own cache as long as it implements the interface
+of [`LightSwitch::NullCache`](lib/light_switch/null_cache.rb).
+
+### ActiveSupport::Notifications
+
+If you wish to be notified of changes made to any switches, you can subscribe
+to [`ActiveSupport::Notifications`](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html)
+published by LightSwitch.  There are three events available:
+
+* `create_committed.switch.light_switch`
+* `destroy_committed.switch.light_switch`
+* `update_committed.switch.light_switch`
+
+An example use case could be logging changes for visibility:
+
+```ruby
+# config/initializers/light_switch.rb
+
+ActiveSupport::Notifications.subscribe("update_committed.switch.light_switch") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  switch = event.payload[:switch]
+
+  Rails.logger.info("#{switch.name} is now #{switch.state}")
+end
+```
+
+The events captured do not capture any meaningful latency metrics. They are just
+published events once changes to a `LightSwitch::Switch` are committed.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "light_switch"
+```
+
+And then execute:
+```bash
+$ bundle
+$ ./bin/rails light_switch:install:migrations db:migrate
+```
+
+Or install it yourself as:
+```bash
+$ gem install light_switch
+```
+
+## Tests
+You can run the tests across all supported Rails versions:
+```
+./bin/appraisal rails test
+```
+
+## Release process
+```
+./bin/release [major|minor|patch]
+```
+
+## Contributing
+Fork this repo and submit a pull request.
+
+If you find a bug or have a feature request, please open a GitHub issue.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/setup"
+require "bundler/gem_version_tasks"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/config/light_switch_manifest.js

@@ -0,0 +1,2 @@
+//= link_directory ../stylesheets/light_switch .css
+//= link_directory ../javascripts/light_switch .js

data/app/assets/images/light_switch/light-switch.svg

@@ -0,0 +1 @@
+<svg xmlns:x="http://ns.adobe.com/Extensibility/1.0/" xmlns:i="http://ns.adobe.com/AdobeIllustrator/10.0/" xmlns:graph="http://ns.adobe.com/Graphs/1.0/" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" x="0px" y="0px" viewBox="0 0 90 112.5" enable-background="new 0 0 90 90" xml:space="preserve"><switch><foreignObject requiredExtensions="http://ns.adobe.com/AdobeIllustrator/10.0/" x="0" y="0" width="1" height="1"/><g i:extraneous="self"><g><path fill="none" d="M60.6,13H29.4c-3.5,0-6.3,2.8-6.3,6.3v51.4c0,3.5,2.8,6.3,6.3,6.3h31.3c3.5,0,6.3-2.8,6.3-6.3V19.3     C67,15.8,64.1,13,60.6,13z M57.8,35.2c0,0.2-0.1,0.3-0.2,0.5l-5.4,8.7c0,0.1,0,0.1,0,0.2l0,12.4c0,0.3-0.1,0.6-0.3,0.8     c-0.2,0.2-0.5,0.3-0.8,0.3H39.8c-0.6,0-1.2-0.5-1.2-1.2V30.4c0-0.6,0.5-1.2,1.2-1.2h2.6l0.2-0.3c0-0.5,0.3-1,0.7-1.2v0h0     c0,0,0,0,0.1,0c0.2-0.1,11.5,0,11.5,0c0.7,0,1.3,0.2,1.4,0.9l1.4,5.8C57.9,34.7,57.9,34.9,57.8,35.2z"/><path d="M60.6,11H29.4c-4.6,0-8.3,3.7-8.3,8.3v51.4c0,4.6,3.7,8.3,8.3,8.3h31.3c4.6,0,8.3-3.7,8.3-8.3V19.3     C69,14.7,65.2,11,60.6,11z M67,70.7c0,3.5-2.8,6.3-6.3,6.3H29.4c-3.5,0-6.3-2.8-6.3-6.3V19.3c0-3.5,2.8-6.3,6.3-6.3h31.3     c3.5,0,6.3,2.8,6.3,6.3V70.7z"/><path d="M56.4,28.6c-0.2-0.6-0.7-0.9-1.4-0.9c0,0-11.3-0.1-11.5,0c0,0,0,0-0.1,0h0v0c-0.5,0.2-0.8,0.7-0.7,1.2l-0.2,0.3h-2.6     c-0.6,0-1.2,0.5-1.2,1.2V57c0,0.6,0.5,1.2,1.2,1.2h11.2c0.3,0,0.6-0.1,0.8-0.3c0.2-0.2,0.3-0.5,0.3-0.8l0-12.4c0-0.1,0-0.1,0-0.2     l5.4-8.7c0.1-0.1,0.1-0.3,0.2-0.5c0.1-0.2,0.2-0.5,0.1-0.8L56.4,28.6z M41,35.9l2.4-3.8l0.7,2.8L41,39.9V35.9z M41,55.8V44.9h8.9     l0,10.9H41z M50.6,42.6h-8.5l4.2-6.7h8.4L50.6,42.6z M46.2,33.6l-0.9-3.5h9.1l0.9,3.5H46.2z"/></g></g></switch></svg>

data/app/assets/javascripts/light_switch/application.js

@@ -0,0 +1 @@
+//= require turbo.min

data/app/assets/stylesheets/light_switch/application.css

@@ -0,0 +1,97 @@
+/*
+ * 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
+ */
+
+.site-header {
+  display: flex;
+  flex-flow: row;
+  align-items: center;
+  margin: 0 0 1em -0.75em;
+}
+
+.site-header h2 {
+  margin-bottom: 0.25em;
+}
+
+.site-header .site-logo {
+  height: 4em;
+}
+
+.container {
+  min-height: 100vh;
+  padding-top: 1em;
+}
+
+#new-switch {
+  padding-bottom: 4em;
+}
+
+.site-footer {
+  position: absolute;
+  bottom: 0;
+  width: 100%;
+  min-height: 3em;
+}
+
+.form-inline {
+  display: flex;
+  flex-flow: row;
+  align-items: center;
+  margin-bottom: 0;
+}
+
+.form-inline label {
+  margin: 0.5em 1em 0.5em 0;
+}
+
+.form-inline input,
+.form-inline button {
+  vertical-align: middle;
+  margin: 0.5em 1em 0.5em 0;
+}
+
+.alert {
+  padding: 1em;
+  background-color: rgba(255, 0, 0, 0.1);
+  border-radius: 0.5em;
+}
+
+.notice {
+  padding: 1em;
+  background-color: rgba(0, 255, 0, 0.1);
+  border-radius: 0.5em;
+}
+
+.mr-1 {
+  margin-right: 1em;
+}
+
+.switch-state {
+  min-width: 3em;
+}
+
+.switch-state-on {
+  font-weight: bold;
+}
+
+input.turn-off {
+  min-width: 12em;
+  background: rgba(255, 0, 0, 0.25);
+}
+
+input.turn-on {
+  background: rgba(0, 255, 0, 0.25);
+  min-width: 12em;
+}