From 0893d55f8b0ff1194986bf0fa1be4e86f09c768c Mon Sep 17 00:00:00 2001 From: Darkweak Date: Sun, 29 Mar 2020 19:33:47 +0200 Subject: [PATCH] Add plantuml diagram and rewrite README parts, add Credits part (#9) * Add puml diagram to md * Some tests * Remove md and switch to puml to svg generator * Improve doc * Update README and plantUML schema --- Makefile | 3 ++ README.md | 51 ++++++++++++++++++---------- docs/plantUML/generate.sh | 6 ++++ docs/plantUML/sequenceDiagram.puml | 42 +++++++++++++++++++++++ docs/plantUML/sequenceDiagram.svg | 54 ++++++++++++++++++++++++++++++ 5 files changed, 139 insertions(+), 17 deletions(-) create mode 100644 docs/plantUML/generate.sh create mode 100644 docs/plantUML/sequenceDiagram.puml create mode 100644 docs/plantUML/sequenceDiagram.svg diff --git a/Makefile b/Makefile index 52363d02b..e32d98914 100644 --- a/Makefile +++ b/Makefile @@ -28,6 +28,9 @@ env-prod: ## Up container with prod env vars cp docker-compose.yml.prod docker-compose.yml cp .env.prod .env +generate-plantUML: ## Generate plantUML diagrams + cd ./docs/plantUML && sh generate.sh && cd ../.. + help: @grep -E '(^[0-9a-zA-Z_-]+:.*?##.*$$)|(^##)' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-25s\033[0m %s\n", $$1, $$2}' | sed -e 's/\[32m##/[33m/' diff --git a/README.md b/README.md index c71087291..c4fec17de 100644 --- a/README.md +++ b/README.md @@ -5,24 +5,26 @@ 2. [Environment variables](#environment-variables) 2.1. [Required variables](#required-variables) 2.2. [Optional variables](#optional-variables) -3. [Cache system](#cache-system) -4. [Exemples](#exemples) - 4.1. [Træfik container](#træfik-container) -5. [SSL](#ssl) - 5.1. [Træfik](#træfik) +3. [Diagrams](#diagrams) + 3.1. [Sequence diagram](#sequence-diagram) +4. [Cache systems](#cache-systems) +5. [Examples](#examples) + 5.1. [Træfik container](#træfik-container) +6. [SSL](#ssl) + 6.1. [Træfik](#træfik) [![Travis CI](https://travis-ci.com/Darkweak/Souin.svg?branch=master)](https://travis-ci.com/Darkweak/Souin) # Souin logoouin reverse-proxy cache ## Project description -Souin is a new cache system any every reverse-proxy. It will be placed on top of your current reverse-proxy whether it's Apache, nginx or Traefik. -Since it's written in go, it can be deployed on any server and thantks docker integration, it will be easy to install it on top of a Swarm or a kubernetes instance. +Souin is a new cache system suitable for every reverse-proxy. It will be placed on top of your current reverse-proxy whether it's Apache, Nginx or Traefik. +As it's written in go, it can be deployed on any server and thanks docker integration, it will be easy to install it on top of a Swarm or a kubernetes instance. ## Environment variables ### Required variables -| Variable | Description | Value exemple | +| Variable | Description | Value example | |:---:|:---:|:---:| |`CACHE_PORT`|The HTTP port Souin will be listening on |`80`| |`CACHE_TLS_PORT`|The TLS port Souin will be listening on|`443`| @@ -31,21 +33,26 @@ Since it's written in go, it can be deployed on any server and thantks docker in |`REVERSE_PROXY`|The reverse-proxy's instance URL (Apache, Nginx, Træfik...)|- `http://yourservice` (Container way)
`http://localhost:81` (Local way)| ### Optional variables -| Variable | Description | Value exemple | +| Variable | Description | Value example | |:---:|:---:|:---:| |`REGEX`|The regex that matches URLs not to store in cache|`http://domain.com/mypath`| -## Cache system -The cache sits into a Redis instance, because setting, getting, updating and deleting keys in Redis is as easy as it gets. -In order to do that, Redis should be on the same network than the Souin instance when using docker-compose. When yousing binaries, then both should be on the same server. -Souin will return the redis instance when it gives a valid answer, or fallback to the reverse proxy otherwise. +## Diagrams + +### Sequence diagram +Sequence diagram + +## Cache systems +The cache system sits on two providers at the moment. It provides an in-memory and redis cache systems because setting, getting, updating and deleting keys in Redis is as easy as it gets. +In order to do that, Redis could be on the same network than the Souin instance when using docker-compose or over the internet then it will use by default in-memory to avoid network latency as much as possible. +Souin will return at first the in-memory response when it gives a non-empty response, then the redis one will be used with same condition, or fallback to the reverse proxy otherwise. ### Cache invalidation The cache invalidation is made for CRUD requests, if you're doing a GET HTTP request, it will serve the cached response when it exists, otherwise the reverse-proxy response will be served. If you're doing a POST, PUT, PATCH or DELETE HTTP request, the related cache GET request will be dropped and the list endpoint will be dropped too It works very well with plain [API Platform](https://api-platform.com) integration (not for custom actions for now) and CRUD routes. -## Exemples +## Examples ### Træfik container [Træfik](https://traefik.io) is a modern reverse-proxy and help you to manage full container architecture projects. @@ -67,6 +74,7 @@ services: command: --providers.docker volumes: - /var/run/docker.sock:/var/run/docker.sock + - /anywhere/traefik.json:/acme.json <<: *networks # your other services here... @@ -103,7 +111,7 @@ services: GOPATH: /app volumes: - ./cmd:/app/cmd - - ./acme.json:/app/src/github.com/darkweak/souin/acme.json + - /anywhere/traefik.json:/ssl/traefik.json <<: *networks redis: @@ -125,16 +133,25 @@ To provide, acme, use just have to map volume as above - /anywhere/traefik.json:/ssl/traefik.json ``` ### Apache -Souin will listen `apache.json` file. You have to setup your own way to agregate your SSL cert files and keys. Alternatively you can use a side project called [dob](https://github.com/darkweak/dob), it's open-source and written in go too +Souin will listen `apache.json` file. You have to setup your own way to aggregate your SSL cert files and keys. Alternatively you can use a side project called [dob](https://github.com/darkweak/dob), it's open-source and written in go too ```yaml volumes: - /anywhere/apache.json:/ssl/apache.json ``` ### Nginx -Souin will listen `nginx.json` file. You have to setup your own way to agregate your SSL cert files and keys. Alternatively you can use a side project called [dob](https://github.com/darkweak/dob), it's open-source and written in go too +Souin will listen `nginx.json` file. You have to setup your own way to aggregate your SSL cert files and keys. Alternatively you can use a side project called [dob](https://github.com/darkweak/dob), it's open-source and written in go too ```yaml volumes: - /anywhere/nginx.json:/ssl/nginx.json ``` At the moment you can't choose the path for the `*.json` in the container, they have to be placed in the `/ssl` folder. In the future you'll be able to do that just setting one env var If none `*.json` is provided to container, a default cert will be served. + + +## Credits + +Thanks to these users for contributing or helping this project in any way +* [oxodao](https://github.com/oxodao) +* [Deuchnord](https://github.com/deuchnord) +* [Sata51](https://github.com/sata51) +* [Pierre Diancourt](https://github.com/pierrediancourt) diff --git a/docs/plantUML/generate.sh b/docs/plantUML/generate.sh new file mode 100644 index 000000000..e42d0618c --- /dev/null +++ b/docs/plantUML/generate.sh @@ -0,0 +1,6 @@ +#!/bin/sh + +for FILE in *.puml; do + cat $FILE | docker run --rm -i think/plantuml > "${FILE%.puml}.svg" +done +echo Done diff --git a/docs/plantUML/sequenceDiagram.puml b/docs/plantUML/sequenceDiagram.puml new file mode 100644 index 000000000..ddf8fdcaa --- /dev/null +++ b/docs/plantUML/sequenceDiagram.puml @@ -0,0 +1,42 @@ +@startuml +actor User +actor System +activate System +participant Souin +collections Providers +participant Memory +participant Redis +participant ReverseProxy +System -> ReverseProxy ++ : run() +System -> Souin ++ : main() +Souin -> Providers : Init() +activate Providers +Providers -> Memory ++ : MemoryConnectionFactory() +Providers <-- Memory : *AbstractProvider +Providers -> Redis ++ : RedisConnectionFactory() +Providers <-- Redis : *AbstractProvider +Souin <-- Providers : AbstractProvider[] +... Waiting for user request ... +loop User requests + User -> Souin : request + activate User + par Request providers content + Souin -> Memory: GetRequestInCache() + else + Souin -> Redis: GetRequestInCache() + else + Souin -> ReverseProxy: GetRequestInReverseProxy() + end + par Response providers content + Souin <-- Memory: *Response + else + Souin <-- Redis: *Response + else + Souin <-- ReverseProxy: *Response + Souin -> Memory: SetRequestInCache() + Souin -> Redis: SetRequestInCache() + end +Souin -> User : response +deactivate User +end +@enduml diff --git a/docs/plantUML/sequenceDiagram.svg b/docs/plantUML/sequenceDiagram.svg new file mode 100644 index 000000000..a152e503f --- /dev/null +++ b/docs/plantUML/sequenceDiagram.svg @@ -0,0 +1,54 @@ +UserUserSystemSystemSouinSouinProvidersProvidersMemoryMemoryRedisRedisReverseProxyReverseProxyrun()main()Init()MemoryConnectionFactory()AbstractProviderRedisConnectionFactory()AbstractProviderAbstractProvider[]Waiting for user requestloop[User requests]requestpar[Request providers content]GetRequestInCache()GetRequestInCache()GetRequestInReverseProxy()par[Response providers content]ResponseResponseResponseSetRequestInCache()SetRequestInCache()response \ No newline at end of file