plausible_proxy_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a6fd09306c6f92c3041adb7a9fe89b59f60ffdfa6e6da65643782a54866c8899
+  data.tar.gz: c9435ee630438eca0e42fca28d5b4c4edea127fc59e63ec70cda0b4aef0a745d
+SHA512:
+  metadata.gz: 845c9759f007c281cf6f034a802cdcc70ded7e2f23ca769101e886dd3647999e7ca90376496e8f78286d755aed56ac0fc1a975017e394b45a5c4fc77f423fe0f
+  data.tar.gz: aa7b72174475d03c2b26baff6fee723b660b9786dc84be48aa66a3fd667a85d372b38b898d52d1d9bbc45adb4f62508ba8a75137334b2d56166c6e0d8f05a6e1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appercept Limited
+
+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,101 @@
+# Plausible Proxy Rails
+
+A Rails Engine that proxies [Plausible Analytics](https://plausible.io) requests through your application server. This keeps analytics working for visitors who block third-party scripts, removes the need for `plausible.io` in your Content Security Policy, and improves visitor privacy by preventing direct connections to external servers.
+
+## How It Works
+
+The gem inserts Rack middleware that intercepts two routes under a configurable proxy path (default: `/ins`):
+
+| Request              | What happens                                                                                   |
+| -------------------- | ---------------------------------------------------------------------------------------------- |
+| `GET /ins/script.js` | Fetches the Plausible script, caches it for 1 hour, and serves it from your domain             |
+| `POST /ins/event`    | Forwards the analytics event payload to the Plausible API with the visitor's IP and User-Agent |
+
+All other requests pass through to your application untouched.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "plausible_proxy_rails"
+```
+
+Then run `bundle install`.
+
+## Configuration
+
+Create an initializer:
+
+```ruby
+# config/initializers/plausible.rb
+PlausibleProxyRails.configure do |config|
+  config.enabled = Rails.env.production?
+  config.domain = "yoursite.com"
+end
+```
+
+### Options
+
+| Option       | Default                               | Description                                                                                                                          |
+| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `enabled`    | `false`                               | Enable the proxy middleware                                                                                                          |
+| `domain`     | `nil`                                 | Your site's domain as registered in Plausible (required)                                                                             |
+| `proxy_path` | `"/ins"`                              | URL path prefix for the proxy endpoints                                                                                              |
+| `script_url` | `"https://plausible.io/js/script.js"` | Plausible script URL — change this to use [script extensions](https://plausible.io/docs/script-extensions) or a self-hosted instance |
+
+The middleware is only activated when `enabled` is `true` **and** `domain` is present.
+
+## Usage
+
+Add the script tag to your layout:
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<head>
+  <%= plausible_tag %>
+</head>
+```
+
+This renders a `<script>` tag that loads the analytics script from your proxy path and sends events through it. When the proxy is disabled (e.g., in development), `plausible_tag` returns `nil` and nothing is rendered.
+
+## Self-Hosted Plausible
+
+If you run a [self-hosted Plausible instance](https://plausible.io/docs/self-hosting), point `script_url` at your server. The event API endpoint is derived from the same host automatically:
+
+```ruby
+PlausibleProxyRails.configure do |config|
+  config.enabled = true
+  config.domain = "yoursite.com"
+  config.script_url = "https://analytics.yoursite.com/js/script.js"
+end
+```
+
+## Plausible Script Options
+
+Plausible provides a site-specific script URL (found in your Plausible account under Site Settings > Site Installation) that looks like `https://plausible.io/js/pa-XXXXXXXXX.js`. This bundles your enabled features automatically. You can also use the generic `https://plausible.io/js/script.js` with [script extensions](https://plausible.io/docs/script-extensions). Either format works with this gem — set your preferred URL as `script_url`:
+
+```ruby
+# Site-specific script
+config.script_url = "https://plausible.io/js/pa-XXXXXXXXX.js"
+
+# Or generic script with extensions
+config.script_url = "https://plausible.io/js/script.file-downloads.outbound-links.js"
+```
+
+See the [Plausible docs](https://plausible.io/docs/plausible-script) for more on script options.
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 7.0
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/appercept/plausible_proxy_rails). See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+This project is intended to be a safe, welcoming space for collaboration. Please follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/Rakefile

@@ -0,0 +1,15 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/app/helpers/plausible_proxy_rails/helper.rb

@@ -0,0 +1,18 @@
+module PlausibleProxyRails
+  module Helper
+    def plausible_tag
+      config = PlausibleProxyRails.configuration
+      return unless config.enabled?
+
+      tag.script(
+        nil,
+        src: "#{config.proxy_path}/script.js",
+        defer: true,
+        data: {
+          domain: config.domain,
+          api: "#{config.proxy_path}/event"
+        }
+      )
+    end
+  end
+end

data/lib/plausible_proxy_rails/configuration.rb

@@ -0,0 +1,15 @@
+module PlausibleProxyRails
+  class Configuration
+    attr_accessor :enabled, :domain, :proxy_path, :script_url
+
+    def initialize
+      @enabled = false
+      @proxy_path = "/ins"
+      @script_url = "https://plausible.io/js/script.js"
+    end
+
+    def enabled?
+      enabled && domain.present?
+    end
+  end
+end

data/lib/plausible_proxy_rails/engine.rb

@@ -0,0 +1,15 @@
+module PlausibleProxyRails
+  class Engine < ::Rails::Engine
+    initializer "plausible_proxy_rails.middleware" do |app|
+      if PlausibleProxyRails.configuration.enabled?
+        app.middleware.use PlausibleProxyRails::Middleware
+      end
+    end
+
+    initializer "plausible_proxy_rails.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include PlausibleProxyRails::Helper
+      end
+    end
+  end
+end

data/lib/plausible_proxy_rails/middleware.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module PlausibleProxyRails
+  class Middleware
+    CACHE_TTL = 3600 # 1 hour in seconds
+
+    def initialize(app)
+      @app = app
+      @script_cache = nil
+      @cached_at = nil
+      @mutex = Mutex.new
+    end
+
+    def call(env)
+      config = PlausibleProxyRails.configuration
+
+      case env["PATH_INFO"]
+      when "#{config.proxy_path}/script.js"
+        serve_script(config)
+      when "#{config.proxy_path}/event"
+        forward_event(env, config)
+      else
+        @app.call(env)
+      end
+    end
+
+    private
+
+    def serve_script(config)
+      body, headers = cached_script(config)
+      [200, headers, [body]]
+    end
+
+    def cached_script(config)
+      @mutex.synchronize do
+        if @script_cache.nil? || (Time.now - @cached_at) > CACHE_TTL
+          fetch_script(config)
+        end
+
+        [@script_cache, @cached_headers]
+      end
+    end
+
+    def fetch_script(config)
+      uri = URI(config.script_url)
+      response = Net::HTTP.get_response(uri)
+
+      @script_cache = response.body
+      @cached_headers = {
+        "content-type" => response["content-type"],
+        "cache-control" => "public, max-age=3600"
+      }
+      @cached_at = Time.now
+    end
+
+    def forward_event(env, config)
+      request = Rack::Request.new(env)
+      body = request.body.read
+
+      script_uri = URI(config.script_url)
+      uri = URI("#{script_uri.scheme}://#{script_uri.host}/api/event")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      post = Net::HTTP::Post.new(uri.path)
+      post["User-Agent"] = env["HTTP_USER_AGENT"]
+      post["X-Forwarded-For"] = env["HTTP_X_FORWARDED_FOR"] || env["REMOTE_ADDR"]
+      post["Content-Type"] = env["CONTENT_TYPE"]
+      post.body = body
+
+      response = http.request(post)
+      response_headers = {"content-type" => response["content-type"]}.compact
+
+      [response.code.to_i, response_headers, [response.body]]
+    end
+  end
+end

data/lib/plausible_proxy_rails/version.rb

@@ -0,0 +1,3 @@
+module PlausibleProxyRails
+  VERSION = "0.1.0"
+end

data/lib/plausible_proxy_rails.rb

@@ -0,0 +1,18 @@
+require "plausible_proxy_rails/engine"
+require "plausible_proxy_rails/version"
+
+module PlausibleProxyRails
+  autoload :Configuration, "plausible_proxy_rails/configuration"
+  autoload :Helper, "plausible_proxy_rails/helper"
+  autoload :Middleware, "plausible_proxy_rails/middleware"
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: plausible_proxy_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Richard Hatherall
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+description: A Rails Engine that proxies Plausible Analytics requests through your
+  application server, improving visitor privacy and removing the need for third-party
+  CSP exceptions.
+email:
+- richard@appercept.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/helpers/plausible_proxy_rails/helper.rb
+- lib/plausible_proxy_rails.rb
+- lib/plausible_proxy_rails/configuration.rb
+- lib/plausible_proxy_rails/engine.rb
+- lib/plausible_proxy_rails/middleware.rb
+- lib/plausible_proxy_rails/version.rb
+homepage: https://github.com/appercept/plausible_proxy_rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/appercept/plausible_proxy_rails
+  source_code_uri: https://github.com/appercept/plausible_proxy_rails
+  changelog_uri: https://github.com/appercept/plausible_proxy_rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Privacy-preserving Plausible Analytics proxy for Rails
+test_files: []