{"id":13880283,"url":"https://github.com/fastly/fastly-rails","last_synced_at":"2025-07-16T16:31:29.526Z","repository":{"id":16147585,"uuid":"18893179","full_name":"fastly/fastly-rails","owner":"fastly","description":"Please visit https://github.com/fastly/fastly-ruby.","archived":true,"fork":false,"pushed_at":"2021-10-20T17:01:23.000Z","size":129,"stargazers_count":144,"open_issues_count":13,"forks_count":66,"subscribers_count":82,"default_branch":"master","last_synced_at":"2025-06-22T05:03:31.024Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastly.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-17T20:54:22.000Z","updated_at":"2024-09-28T04:01:09.000Z","dependencies_parsed_at":"2022-08-04T08:00:15.461Z","dependency_job_id":null,"html_url":"https://github.com/fastly/fastly-rails","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/fastly/fastly-rails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastly%2Ffastly-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastly%2Ffastly-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastly%2Ffastly-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastly%2Ffastly-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastly","download_url":"https://codeload.github.com/fastly/fastly-rails/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastly%2Ffastly-rails/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265524632,"owners_count":23782016,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:02:54.896Z","updated_at":"2025-07-16T16:31:28.979Z","avatar_url":"https://github.com/fastly.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Fastly Rails Plugin [![Build Status](https://travis-ci.org/fastly/fastly-rails.svg?branch=master)](https://travis-ci.org/fastly/fastly-rails)\n\n**Deprecation Notice**\n\nThis repository has been deprecated. The official Fastly Ruby [client](https://docs.fastly.com/api/clients#ruby) is the [fastly-ruby](https://github.com/fastly/fastly-ruby) gem.\n\nAlthough this repository is no longer supported, it could be useful as a reference.\n\n----\n\n# Introduction\nFastly dynamic caching integration for Rails.\n\nTo use Fastly dynamic caching, you tag *any* response you wish to cache with unique Surrogate-Key HTTP Header(s) and then hit the Fastly API purge endpoint with the surrogate key when the response changes. The purge instantly replaces the cached response with a fresh response from origin.\n\nThis plugin provides three main things:\n- Instance and class methods on ActiveRecord (or Mongoid) objects for surrogate keys and purging\n- Controller helpers to set Cache-Control and Surrogate-Control response headers\n- A controller helper to set Surrogate-Key headers on responses\n\nIf you're not familiar with Fastly Surrogate Keys, you might want to check out [API Caching](http://www.fastly.com/blog/api-caching-part-1) and [Fastly Surrogate Keys](http://www.fastly.com/blog/surrogate-keys-part-1) for a primer.\n\n# Setup\n\nAdd to your Gemfile\n\n````ruby\ngem 'fastly-rails'\n````\n\n## Configuration\n\nFor information about how to find your Fastly API Key or a Fastly Service ID, refer to our [documentation](https://docs.fastly.com/guides/account-management-and-security/finding-and-managing-your-account-info).\n\nCreate an initializer for Fastly configuration\n\n````ruby\nFastlyRails.configure do |c|\n  c.api_key = ENV['FASTLY_API_KEY']  # Fastly api key, required\n  c.max_age = 86400                  # time in seconds, optional, defaults to 2592000 (30 days)\n  c.stale_while_revalidate = 86400   # time in seconds, optional, defaults to nil\n  c.stale_if_error = 86400           # time in seconds, optional, defaults to nil\n  c.service_id = ENV['SERVICE_ID']   # The Fastly service you will be using, required\n  c.purging_enabled = !Rails.env.development? # No need to configure a client locally (AVAILABLE ONLY AS OF 0.4.0)\nend\n````\n\u003e Note: purging only requires that you authenticate with your `api_key`. However, you can provide a `user` and `password` if you are using other endpoints in fastly-ruby that require full-auth.\n\u003e Also, you must provide a service_id for purges to work.\n\n## Usage\n\n### Surrogate Keys\n\nSurrogate keys are what Fastly uses to purge groups of individual objects from our caches.\n\nThis plugin adds a few methods to generate surrogate keys automatically.  `table_key` and `record_key` methods are added to any ActiveRecord::Base instance.  `table_key` is also added to any ActiveRecord::Base class.  In fact, `table_key` on an instance just calls `table_key` on the class.\n\nWe've chosen a simple surrogate key pattern by default. It is:\n\n````ruby\ntable_key: self.class.table_key # calls table_name on the class\nrecord_key: \"#{table_key}/#{self.id}\"\n````\n\ne.g. If you have an ActiveRecord Model named Book.\n\n````ruby\ntable key: books\nrecord key: books/1, books/2, books/3, etc...\n````\n\nYou can easily override these methods in your models to use custom surrogate keys that may fit your specific application better:\n\n````ruby\ndef self.table_key\n  \"my_custom_table_key\"\nend\n\ndef record_key\n  \"my_custom_record_key\"# Ensure these are unique for each record\nend\n````\n\n### Headers\n\nThis plugin adds a `set_cache_control_headers` method to ActionController. You'll need to add this in a `before_filter` or `after_filter` [see note on cookies below](https://github.com/fastly/fastly-rails#sessions-cookies-and-private-data) to any controller action that you wish to edge cache (see example below). The method sets Cache-Control and Surrogate-Control HTTP Headers with a default of 30 days (remember you can configure this, see the initializer setup above).\n\nIt's up to you to set Surrogate-Key headers for objects that you want to be able to purge.\n\nTo do this use the `set_surrogate_key_header` method on GET actions.\n\n````ruby\nclass BooksController \u003c ApplicationController\n  # include this before_filter in controller endpoints that you wish to edge cache\n  before_filter :set_cache_control_headers, only: [:index, :show]\n  # This can be used with any customer actions. Set these headers for GETs that you want to cache\n  # e.g. before_filter :set_cache_control_headers, only: [:index, :show, :my_custom_action]\n\n  def index\n    @books = Book.all\n    set_surrogate_key_header 'books', @books.map(\u0026:record_key)\n  end\n\n  def show\n    @book = Book.find(params[:id])\n    set_surrogate_key_header @book.record_key\n  end\nend\n````\n\n### Purges\n\nAny object that inherits from ActiveRecord will have `purge_all`, `soft_purge_all`, and `table_key` class methods available as well as `purge`, `soft_purge`, `purge_all`, and `soft_purge_all` instance methods.\n\nExample usage is show below.\n\n````ruby\nclass BooksController \u003c ApplicationController\n\n  def create\n    @book = Book.new(params)\n    if @book.save\n      @book.purge_all\n      render @book\n    end\n  end\n\n  def update\n    @book = Book.find(params[:id])\n    if @book.update(params)\n      @book.purge\n      render @book\n    end\n  end\n\n  def delete\n    @book = Book.find(params[:id])\n    if @book.destroy\n      @book.purge # purge the record\n      @book.purge_all # purge the collection so the record is no longer there\n    end\n  end\nend\n````\n\nTo simplify controller methods, you could use ActiveRecord callbacks. e.g.\n\n````ruby\nclass Book \u003c ActiveRecord::Base\n  after_create :purge_all\n  after_save :purge\n  after_destroy :purge, :purge_all\n  ...\n\nend\n````\n\nWe have left these out intentially, as they could potentially cause issues when running locally or testing. If you do use these, pay attention, as using callbacks could also inadvertently overwrite HTTP Headers like Cache-Control or Set-Cookie and cause responses to not be properly cached.\n\n### Service id\n\nOne thing to note is that currently we expect a service_id to be defined in your FastlyRails.configuration.  However, we've added localized methods so that your models can override your global service_id, if you needed to operate on more than one for any reason.  NOTE: As of 0.3.0, we've renamed the class-level and instance-level `service_id` methods to `fastly_service_identifier` in the active_record and mongoid mix-ins.  See the CHANGELOG for a link to the Github issue.\n\nCurrently, this would require you to basically redefine `fastly_service_identifier` on the class level of your model:\n\n````ruby\nclass Book \u003c ActiveRecord::Base\n  def self.fastly_service_identifier\n    'MYSERVICEID'\n  end\nend\n````\n\n\n### Sessions, Cookies, and private data\n\nBy default, Fastly will not cache any response containing a `Set-Cookie` header. In general, this is beneficial because caching responses that contain sensitive data is typically not done on shared caches.\n\nIn this plugin the `set_cache_control_headers` method removes the `Set-Cookie` header from a\nrequest. In some cases, other libraries, particularily middleware, may insert or modify HTTP Headers outside the scope of where the `set_cache_control_heades` method is invoked in a controller action. For example, some authentication middleware will add a `Set-Cookie` header into requests *after* fastly-rails removes it.\n\nThis can cause some requests that can (and should) be cached to not be cached due to the presence of `Set-Cookie`.\n\nIn order to remove the `Set-Cookie` header in these cases, fastly-rails provides an optional\npiece of middleware that removes `Set-Cookie` when the `Surrogate-Control` or `Surrogate-Key`\nheader is present (the `Surrogate-Control` header is also inserted by the\n`set_cache_control_headers` method and indicates that you want the endpoint to\nbe cached by Fastly and do not need cookies).\n\n#### fastly-rails middleware to delete `Set-Cookie`\n\nTo override a piece of middleware in Rails, insert custom middleware before\nit. Once you've identified which middleware is inserting the `Set-Cookie`\nheader, add the following (in this example, `ExampleMiddleware` is what we are\ntrying to override`:\n\n```ruby\n# config/application.rb\n\n  config.middleware.insert_before(\n    ExampleMiddleware,\n    \"FastlyRails::Rack::RemoveSetCookieHeader\"\n  )\n```\n\n\n\n### Example\n\nCheck out our example [todo app](https://github.com/mmay/todo) which has a full example of fastly-rails integration in a simple rails app.\n\n## Future Work\n\n- Add an option to send purges in batches.\n\n\u003e This will cut down on response delay from waiting for large amounts of purges to happen. This would primarily be geared towards write-heavy apps.\n\n- Your feedback\n\n## Testing\n\nFirst, install all required gems:\n\n```sh\n$ appraisal install\n```\n\nThis engine is capable of testing against multiple versions of Rails.  It uses the appraisal gem.  To make this happen, use the appraisal command in lieu of `rake test`:\n\n```sh\n$ appraisal rake test # tests against all the defined versions in the Appraisals file\n\n$ appraisal rails-3 rake test # finds a defined version in the Appraisals file called \"rails-3\" and only runs tests against this version\n````\n\n## Supported Platforms\nWe [run tests](https://travis-ci.org/fastly/fastly-rails) using all combinations of the following versions of Ruby and Rails:\n\nRuby:\n  - 1.9.3\n  - 2.1.1\n\nRails:\n  - v3.2.18\n  - v4.0.5\n  - v4.1.1\n\n### Other Platforms\nAs of v0.1.2, *experimental* Mongoid support was added by @joshfrench of [Upworthy](http://www.upworthy.com/).\n\n## Credits\n\nThis plugin was developed by [Fastly](http://www.fastly.com/) with lots of help from our friend at [Hotel Tonight](http://www.hoteltonight.com), [Harlow Ward](https://twitter.com/futuresanta). Check out his blog about [Cache Invalidation with Fastly Surrogate Keys](http://www.hward.com/varnish-cache-invalidation-with-fastly-surrogate-keys) which is where many of the ideas used in this plugin originated.\n\n--\nThis project rocks and uses MIT-LICENSE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastly%2Ffastly-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastly%2Ffastly-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastly%2Ffastly-rails/lists"}