Souin Table of Contents

1. Souin reverse-proxy cache description
2. Configuration
   2.1. Required configuration
   2.1.1. Souin as plugin
   2.1.2. Souin out-of-the-box
   2.2. Optional configuration
3. Storages
4. APIs
   4.1. Prometheus API
   4.2. Souin API
   4.3. Security API
5. Diagrams
   5.1. Sequence diagram
6. Cache systems
7. GraphQL
8. Plugins
   8.1. Beego filter
   8.2. Caddy module
   8.3. Chi middleware
   8.4. Dotweb middleware
   8.5. Echo middleware
   8.6. Fiber middleware
   8.7. Gin middleware
   8.8. Goa middleware
   8.9. Go-zero middleware
   8.10. Goyave middleware
   8.11. Hertz middleware
   8.12. Kratos filter
   8.13. Roadrunner middleware
   8.14. Skipper filter
   8.15. Træfik plugin
   8.16. Tyk plugin
   8.17. Webgo middleware
9. Credits

Souin HTTP cache

Project description

Souin is a new HTTP cache system suitable for every reverse-proxy. It can be either placed on top of your current reverse-proxy whether it's Apache, Nginx or as plugin in your favorite reverse-proxy like Træfik, Caddy or Tyk.
Since it's written in go, it can be deployed on any server and thanks to the docker integration, it will be easy to install on top of a Swarm, or a kubernetes instance.
It's RFC compatible, supporting Vary, request coalescing, stale cache-control and other specifications related to the RFC-7234.
It supports the newly written RFCs (currently in draft) http-cache-groups and http-invalidation.
It also supports the Cache-Status HTTP response header, the YKey group such as Varnish, the Targeted HTTP Cache Control RFC, .
It supports the ESI tags, thanks to the go-esi package.

[!WARNING] Since v1.7.0 Souin implements only one storage. If you need a specific storage you have to take it from the storages repository and add it either in your code, during the build otherwise.
(e.g. with otter using caddy) You have to build your caddy module with the desired storage xcaddy build --with github.com/darkweak/souin/plugins/caddy --with github.com/darkweak/storages/otter/caddy and configure otter in your Caddyfile/JSON configuration file.
See the storages section or the documentation website about the storages.

Configuration

The configuration file is store at /anywhere/configuration.yml. You can supply your own as long as you use one of the minimal configurations below.

Required configuration

Souin as plugin

default_cache: # Required
  ttl: 10s # Default TTL

Souin out-of-the-box

default_cache: # Required
  ttl: 10s # Default TTL
reverse_proxy_url: 'http://traefik' # If it's in the same network you can use http://your-service, otherwise just use https://yourdomain.com

Besides, it's highly recommended to set default_cache.default_cache_control (see it below) to avoid undesired caching for responses without Cache-Control header.

Optional configuration

# /anywhere/configuration.yml
api:
  basepath: /souin-api # Default route basepath for every additional APIs to avoid conflicts with existing routes
  prometheus: # Prometheus exposed metrics
    basepath: /anything-for-prometheus-metrics # Change the prometheus endpoint basepath
  souin: # Souin listing keys and cache management
    basepath: /anything-for-souin # Change the souin endpoint basepath
cache_keys:
  '.*\.css':
    disable_body: true # Prevent the body from being used in the cache key
    disable_host: true # Prevent the host from being used in the cache key
    disable_method: true # Prevent the method from being used in the cache key
    disable_query: true # Prevent the query string from being used in the cache key
    disable_scheme: true # request scheme the query string from being used in the cache key
    disable_vary: true # Prevent the varied headers string from being used in the cache key
    hash: true # Hash the cache key instead of a plaintext one
    hide: true # Prevent the cache key to be in the response Cache-Status header
    headers: # Add headers to the key
      - Authorization # Add the header value in the key
      - Content-Type # Add the header value in the key
    template: "{http.request.method}-{http.request.host}-{http.request.path}" # Use caddy placeholders to create the key (when this option is enabled, disable_* directives are skipped)
cdn: # If Souin is set after a CDN fill these informations
  api_key: XXXX # Your provider API key if mandatory
  provider: fastly # The provider placed before Souin (e.g. fastly, cloudflare, akamai, varnish)
  strategy: soft # The strategy to purge the CDN cache based on tags (e.g. soft, hard)
  dynamic: true # If true, you'll be able to add custom keys than the ones defined under the surrogate_keys key
default_cache:
  allowed_http_verbs: # Allowed HTTP verbs to cache (default GET, HEAD).
    - GET
    - POST
    - HEAD
  allowed_additional_status_codes: # Allowed additional HTTP status code to cache.
    - 202
    - 400
  cache_name: Souin # Override the cache name to use in the Cache-Status header
  distributed: true # Use Olric or Etcd distributed storage
  key:
    disable_body: true # Prevent the body from being used in the cache key
    disable_host: true # Prevent the host from being used in the cache key
    disable_method: true # Prevent the method from being used in the cache key
    disable_query: true # Prevent the query string from being used in the cache key
    disable_scheme: true # Prevent the request scheme string from being used in the cache key
    disable_vary: true # Prevent the varied headers string from being used in the cache key
    hash: true # Hash the cache key instead of a plaintext one
    hide: true # Prevent the cache key to be in the response Cache-Status header
    headers: # Add headers to the key
      - Authorization # Add the header value in the key
      - Content-Type # Add the header value in the key
    template: "{http.request.method}-{http.request.host}-{http.request.path}" # Use caddy placeholders to create the key (when this option is enabled, disable_* directives are skipped)
  etcd: # If distributed is set to true, you'll have to define either the etcd or olric section
    configuration: # Configure directly the Etcd client
      endpoints: # Define multiple endpoints
        - etcd-1:2379 # First node
        - etcd-2:2379 # Second node
        - etcd-3:2379 # Third node
  mode: bypass # Override the RFC respect.
  olric: # If distributed is set to true, you'll have to define either the etcd or olric section
    url: 'olric:3320' # Olric server
  regex:
    exclude: 'ARegexHere' # Regex to exclude from cache
  stale: 1000s # Stale duration
  timeout: # Timeout configuration
    backend: 10s # Backend timeout before returning an HTTP unavailable response
    cache: 20ms # Cache provider (badger, etcd, nutsdb, olric, depending the configuration you set) timeout before returning a miss
  ttl: 1000s # Default TTL
  default_cache_control: no-store # Set default value for Cache-Control response header if not set by upstream
log_level: INFO # Logs verbosity [ DEBUG, INFO, WARN, ERROR, DPANIC, PANIC, FATAL ], case do not matter
ssl_providers: # The {providers}.json to use
  - traefik
urls:
  'https:\/\/domain.com\/first-.+': # First regex route configuration
    ttl: 1000s # Override default TTL
  'https:\/\/domain.com\/second-route': # Second regex route configuration
    ttl: 10s # Override default TTL
  'https?:\/\/mysubdomain\.domain\.com': # Third regex route configuration
    ttl: 50s # Override default TTL'
    default_cache_control: public, max-age=86400 # Override default default Cache-Control
ykeys:
  The_First_Test:
    headers:
      Content-Type: '.+'
  The_Second_Test:
    url: 'the/second/.+'
  The_Third_Test:
  The_Fourth_Test:
surrogate_keys:
  The_First_Test:
    headers:
      Content-Type: '.+'
  The_Second_Test:
    url: 'the/second/.+'
  The_Third_Test:
  The_Fourth_Test:

(default: /souin-api) | | api.{api}.enable | (DEPRECATED) Enable the API with related routes | true

(default: true if you define the api name, false then) | | api.{api}.security | (DEPRECATED) Enable the JWT Authentication token verification | true

(default: false) | | api.security.secret | (DEPRECATED) JWT secret key | Any_charCanW0rk123 | | api.security.users | (DEPRECATED) Array of authorized users with username x password combo | - username: admin

password: admin | | api.souin.security | Enable JWT validation to access the resource | true

(default: false) | | cache_keys | Define the key generation rules for each URI matching the key regexp | | | cache_keys.{your regexp} | Regexp that the URI should match to override the k