feat(documentation): prepare release with external storages

darkweak · Jul 10, 2024 · bb573e6 · bb573e6
1 parent 8e4886c
commit bb573e6
Show file tree

Hide file tree

Showing 16 changed files with 494 additions and 79 deletions.
diff --git a/README.md b/README.md
@@ -7,16 +7,15 @@
     2.1.1. [Souin as plugin](#souin-as-plugin)  
     2.1.2. [Souin out-of-the-box](#souin-out-of-the-box)  
   2.2. [Optional configuration](#optional-configuration)
-3. [APIs](#apis)  
-  3.1. [Prometheus API](#prometheus-api)  
-  3.2. [Souin API](#souin-api)  
-  3.3. [Security API](#security-api)
-4. [Diagrams](#diagrams)  
-  4.1. [Sequence diagram](#sequence-diagram)
-5. [Cache systems](#cache-systems)
-6. [GraphQL](#graphql)  
-7. [Examples](#examples)  
-  7.1. [Træfik container](#træfik-container)
+3. [Storages](#storages)  
+4. [APIs](#apis)  
+  4.1. [Prometheus API](#prometheus-api)  
+  4.2. [Souin API](#souin-api)  
+  4.3. [Security API](#security-api)
+5. [Diagrams](#diagrams)  
+  5.1. [Sequence diagram](#sequence-diagram)
+6. [Cache systems](#cache-systems)
+7. [GraphQL](#graphql)  
 8. [Plugins](#plugins)  
   8.1. [Beego filter](#beego-filter)  
   8.2. [Caddy module](#caddy-module)  
@@ -35,8 +34,6 @@
   8.15. [Træfik plugin](#træfik-plugin)  
   8.16. [Tyk plugin](#tyk-plugin)  
   8.17. [Webgo middleware](#webgo-middleware)  
-  8.18. [Prestashop plugin](#prestashop-plugin)  
-  8.19. [Wordpress plugin](#wordpress-plugin)  
 9. [Credits](#credits)
 
 # Souin HTTP cache
@@ -46,9 +43,14 @@ Souin is a new HTTP cache system suitable for every reverse-proxy. It can be eit
 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](https://tools.ietf.org/html/rfc7234).  
 It supports the newly written RFCs (currently in draft) [http-cache-groups](https://datatracker.ietf.org/doc/draft-nottingham-http-cache-groups/) and [http-invalidation](https://datatracker.ietf.org/doc/draft-nottingham-http-invalidation/).  
-It also supports the [Cache-Status HTTP response header](https://www.rfc-editor.org/rfc/rfc9211) and the YKey group such as Varnish.  
+It also supports the [Cache-Status HTTP response header](https://www.rfc-editor.org/rfc/rfc9211), the YKey group such as Varnish, the [Targeted HTTP Cache Control RFC](https://www.rfc-editor.org/rfc/rfc9213), .  
 It supports the ESI tags, thanks to the [go-esi package](https://github.com/darkweak/go-esi).
 
+> [!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](https://github.com/darkweak/storages) 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](#storages) or the [documentation website about the storages](https://docs.souin.io/docs/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.
 
@@ -93,6 +95,7 @@ cache_keys:
     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)
@@ -211,7 +214,7 @@ surrogate_keys:
 | `default_cache.key.headers`                       | Add headers to the key matching the regexp                                                                                                  | `- Authorization`<br/><br/>`- Content-Type`<br/><br/>`- X-Additional-Header`                                              |
 | `default_cache.key.hide`                          | Prevent the key from being exposed in the `Cache-Status` HTTP response header                                                               | `true`<br/><br/>`(default: false)`                                                                                        |
 | `default_cache.key.template`                      | Use caddy placeholders to create the key (when this option is enabled, disable_* directives are skipped)                                    | [Placeholders documentation](https://caddyserver.com/docs/caddyfile/concepts#placeholders)                                |
-| `default_cache.max_cacheable_body_bytes`           | Set the maximum size (in bytes) for a response body to be cached (unlimited if omited)                                                      | `1048576` (1MB)                                                                                                           |
+| `default_cache.max_cacheable_body_bytes`          | Set the maximum size (in bytes) for a response body to be cached (unlimited if omited)                                                      | `1048576` (1MB)                                                                                                           |
 | `default_cache.mode`                              | RFC respect tweaking                                                                                                                        | One of `bypass` `bypass_request` `bypass_response` `strict` (default `strict`)                                            |
 | `default_cache.nuts`                              | Configure the Nuts cache storage                                                                                                            |                                                                                                                           |
 | `default_cache.nuts.path`                         | Set the Nuts file path storage                                                                                                              | `/anywhere/nuts/storage`                                                                                                  |
@@ -379,60 +382,6 @@ The cache invalidation is built for CRUD requests, if you're doing a GET HTTP re
 If you're doing a POST, PUT, PATCH or DELETE HTTP request, the related cache GET request, and the list endpoint will be dropped.  
 It also supports invalidation via [Souin API](#souin-api) to invalidate the cache programmatically.
 
-## Examples
-
-### Træfik container
-[Træfik](https://traefik.io) is a modern reverse-proxy which helps you to manage full container architecture projects.
-
-```yaml
-# your-traefik-instance/docker-compose.yml
-version: '3.7'
-
-x-networks: &networks
-  networks:
-    - your_network
-
-services:
-  traefik:
-    image: traefik:v2.5.6
-    command: --providers.docker
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-      - /anywhere/traefik.json:/acme.json
-    <<: *networks
-
-  # your other services here...
-
-networks:
-  your_network:
-    external: true
-```
-
-```yaml
-# your-souin-instance/docker-compose.yml
-version: '3.7'
-
-x-networks: &networks
-  networks:
-    - your_network
-
-services:
-  souin:
-    image: darkweak/souin:latest
-    ports:
-      - 80:80
-      - 443:443
-    environment:
-      GOPATH: /app
-    volumes:
-      - /anywhere/traefik.json:/ssl/traefik.json
-      - /anywhere/configuration.yml:/configuration/configuration.yml
-    <<: *networks
-
-networks:
-  your_network:
-    external: true
-```
 
 ## Plugins
 
@@ -1158,17 +1107,14 @@ func main(){
 }
 ```
 
-### Prestashop plugin
-A repository called [prestashop-souin](https://github.com/lucmichalski/prestashop-souin) has been started by [lucmichalski](https://github.com/lucmichalski). You can manage your Souin instance through the admin panel UI.
-
-### Wordpress plugin
-A repository called [wordpress-souin](https://github.com/Darkweak/wordpress-souin) to be able to manage your Souin instance through the admin panel UI.
-
 ## Credits
 
 Thanks to these users for contributing or helping this project in any way  
 * [Oxodao](https://github.com/oxodao)
 * [Deuchnord](https://github.com/deuchnord)
+* [Vincent Jordan](https://github.com/vejipe)
+* [Mohammed Al Sahaf](https://github.com/mohammed90)
+* [Hussam Almarzooq](https://github.com/hussam-almarzoq)
 * [Sata51](https://github.com/sata51)
 * [Pierre Diancourt](https://github.com/pierrediancourt)
 * [Burak Sezer](https://github.com/buraksezer)
@@ -1192,3 +1138,7 @@ Thanks to these users for contributing or helping this project in any way
 * [JacquesDurand](https://github.com/jacquesdurand)
 * [Frederic Houle](https://github.com/frederichoule)
 * [Valery Piashchynski](https://github.com/rustatian)
+* [Ivan Derda](https://github.com/HobMartin)
+* [p0358](https://github.com/p0358)
+* [Alberto Tablado](https://github.com/aluki)
+* [Yong Zhang](https://github.com/yongzhang)
diff --git a/docs/website/assets/docs/scss/style.scss b/docs/website/assets/docs/scss/style.scss
@@ -73,15 +73,31 @@ $code-block-padding-top: {{ if eq .Site.Params.docs.prism true -}}0{{ else }}1.2
 @import "custom/plugins/mermaid/mermaid";
 
 h1 {
-    padding-top: 1em;
-    padding-bottom: 1em;
+    margin-top: .5em;
+    font-weight: 900 !important;
+    margin-left: auto;
+    margin-right: auto;
+    padding: 0.1em 0.4em;
+    border-radius: 0.8em 0.3em;
+    background: transparent;
+    background-image: linear-gradient(
+        to right,
+        hsla(226, 66, 51, 0.3),
+        hsla(226, 66, 51, 0.1)
+    );
+    -webkit-box-decoration-break: clone;
+    box-decoration-break: clone;
 }
 
 h2 {
-    padding-top: 0.5em;
+    padding-top: 1.5em;
     padding-bottom: 0.5em;
 }
 
+h4 {
+    padding-top: 0.75em;
+}
+
 div.code-toolbar {
     border-radius: 1rem;
     & > pre {
@@ -115,4 +131,8 @@ div.code-toolbar {
             display: flex;
         }
     }
+}
+
+.alert > .w-100 {
+    overflow: hidden
 }
diff --git a/docs/website/content/docs/configuration.md b/docs/website/content/docs/configuration.md
@@ -48,9 +48,13 @@ cache_keys:
         disable_host: true
         disable_method: true
         disable_query: true
+        disable_scheme: true
+        hash: true
         headers:
             - Authorization
             - Content-Type
+        hide: true
+        template: "{http.request.method}-{http.request.host}-{http.request.path}"
 ```
 {{% /alert %}}
 
@@ -77,6 +81,8 @@ default: `false`
 * **hide**: Prevent the key from being exposed in the `Cache-Status` HTTP response header.  
 default: `false`
 
+* **template**: Customize the key with the given template. It uses the caddy placeholders to create the key (when this option is enabled, disable_* directives are skipped).  
+
 
 ### CDN
 The cdn prefix configure the upfront CDN yuo have placed before Souin. It can handle ofr you the cache invalidation on your CDN, the optimization to have your pages cached directly on it.
@@ -164,6 +170,8 @@ default: `false`
 * **hide**: Prevent the key from being exposed in the `Cache-Status` HTTP response header.  
 default: `false`
 
+* **template**: Customize the key with the given template. It uses the caddy placeholders to create the key (when this option is enabled, disable_* directives are skipped).  
+
 #### Max cacheable body bytes
 Limit to define if the body size is allowed to be cached. (e.g. `1048576` (1MB)).  
 If a limit is set, your streamed/chunk responses won't be cached.  

diff --git a/docs/website/content/docs/introduction.md b/docs/website/content/docs/introduction.md
@@ -19,6 +19,17 @@ Souin is a powerful HTTP cache system written in go and implements the following
 
 
 ## Multiple backend storages
+
+{{% alert context="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](https://github.com/darkweak/storages) 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 
+```shell
+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 page]({{% relref "/docs/storages" %}}) to learn more about each supported storage.
+{{% /alert %}}
+
 ### Local in-memory or filesystem
 * [Badger]({{% relref "/docs/storages/badger" %}})
 * [Nuts]({{% relref "/docs/storages/nuts" %}})

diff --git a/docs/website/content/docs/middlewares/caddy.md b/docs/website/content/docs/middlewares/caddy.md
@@ -28,7 +28,6 @@ We need to tell caddy that it must use the HTTP cache with the `cache` global an
 ```caddyfile
 {
     debug
-    cache order before rewrite
     cache {
         ttl 1h
     }
@@ -83,6 +82,32 @@ If we go on [https://localhost/souin-api/debug/](https://localhost/souin-api/deb
 ### Complex configuration
 
 #### Storages
+{{% alert context="warning" %}}
+Since `v1.7.0` Souin implements only an in-memory storage, if you need a specific storage you have to take it from [the storages repository](https://github.com/darkweak/storages) and add to your build command.  
+(e.g. with redis using caddy) You have to build your caddy module with the desired storage 
+```shell
+xcaddy build --with github.com/darkweak/souin/plugins/caddy --with github.com/darkweak/storages/redis/caddy
+```
+and configure redis in your Caddyfile/JSON configuration file.  
+See the [storages page]({{% relref "/docs/storages" %}}) to learn more about each supported storage.
+{{% /alert %}}
+
+First you have to build Caddy with Souin and a storage using the following template.
+```
+xcaddy build \
+    --with github.com/darkweak/souin/plugins/caddy \
+    --with github.com/darkweak/storages/{your_storage_name}/caddy
+```
+
+You can also use as many storages you want.
+```
+xcaddy build \
+    --with github.com/darkweak/souin/plugins/caddy \
+    --with github.com/darkweak/storages/redis/caddy
+    --with github.com/darkweak/storages/nuts/caddy
+    --with github.com/darkweak/storages/otter/caddy
+```
+
 We can define multiple storages to use to store the response from the upstream server and specify the order.
 Here, we define 3 storages `badger`, `nuts` and `redis` and `nuts` will be accessed first, `badger` the second and `redis` the third only if the previous doesn't return suitable data.