Merge pull request #127 from Kuadrant/docs

README.md

@@ -3,17 +3,16 @@
 [![Limitador GH Workflow](https://github.com/Kuadrant/limitador/actions/workflows/rust.yml/badge.svg)](https://github.com/Kuadrant/limitador/actions/workflows/rust.yml)
 [![docs.rs](https://docs.rs/limitador/badge.svg)](https://docs.rs/limitador)
 [![Crates.io](https://img.shields.io/crates/v/limitador)](https://crates.io/crates/limitador)
-[![Docker Repository on Quay](https://quay.io/repository/3scale/limitador/status
-"Docker Repository on Quay")](https://quay.io/repository/3scale/limitador)
+[![Docker Repository on Quay](https://quay.io/repository/kuadrant/limitador/status
+"Docker Repository on Quay")](https://quay.io/repository/kuadrant/limitador)
 
 Limitador is a generic rate-limiter written in Rust. It can be used as a
-library, or as a service. The service exposes HTTP endpoints to apply and manage
+library, or as a service. The service exposes HTTP endpoints to apply and observe
 limits. Limitador can be used with Envoy because it also exposes a grpc service, on a different
 port, that implements the Envoy Rate Limit protocol (v3).
 
 - [**Getting started**](#getting-started)
 - [**How it works**](/doc/how-it-works.md)
-- [**Limits storage**](#limits-storage)
 - [**Development**](#development)
 - [**Testing Environment**](limitador-server/docs/sandbox.md)
 - [**Kubernetes**](limitador-server/kubernetes/)
@@ -31,70 +30,25 @@ Limitador is under active development, and its API has not been stabilized yet.
 Add this to your `Cargo.toml`:
 ```toml
 [dependencies]
-limitador = { version = "0.2.0" }
+limitador = { version = "0.3.0" }
 ```
 
-To use Limitador in a project that compiles to WASM, there are some features
-that need to be disabled. Add this to your `Cargo.toml` instead:
-```toml
-[dependencies]
-limitador = { version = "0.2.0", default-features = false }
-```
+For more information, see the [`README` of the crate](limitador/README.md)
 
 ### Server
 
 Run with Docker (replace `latest` with the version you want):
 ```bash
-docker run --rm --net=host -it quay.io/3scale/limitador:latest
+docker run --rm --net=host -it quay.io/kuadrant/limitador:v1.0.0
 ```
 
 Run locally:
 ```bash
-cargo run --release --bin limitador-server
-```
-
-To use Redis, specify the URL with `REDIS_URL`:
-```bash
-REDIS_URL=redis://127.0.0.1:6379 cargo run --release --bin limitador-server
-```
-
-By default, Limitador starts the HTTP server in `localhost:8080` and the grpc
-service that implements the Envoy Rate Limit protocol in `localhost:8081`. That
-can be configured with these ENVs: `ENVOY_RLS_HOST`, `ENVOY_RLS_PORT`,
-`HTTP_API_HOST`, and `HTTP_API_PORT`.
-
-The OpenAPI spec of the HTTP service is
-[here](limitador-server/docs/http_server_spec.json).
-
-Limitador can be started with a YAML file that has some limits predefined. Keep
-in mind that they can be modified using the HTTP API. There's an [example
-file](limitador-server/examples/limits.yaml) that allows 10 requests per minute
-and per user_id when the HTTP method is "GET" and 5 when it is a "POST". You can
-run it with Docker (replace `latest` with the version you want):
-```bash
-docker run -e LIMITS_FILE=/home/limitador/my_limits.yaml --rm --net=host -it -v $(pwd)/limitador-server/examples/limits.yaml:/home/limitador/my_limits.yaml:ro quay.io/3scale/limitador:latest
-```
-
-You can also use the YAML file when running locally:
-```bash
-LIMITS_FILE=./limitador-server/examples/limits.yaml cargo run --release --bin limitador-server
+cargo run --release --bin limitador-server -- --help
 ```
 
-If you want to use Limitador with Envoy, there's a minimal Envoy config for
-testing purposes [here](limitador-server/examples/envoy.yaml). The config
-forwards the "userid" header and the request method to Limitador. It assumes
-that there's an upstream API deployed on port 1323. You can use
-[echo](https://github.com/labstack/echo), for example.
-
-Limitador has several options that can be configured via ENV. This
-[doc](limitador-server/docs/configuration.md) specifies them.
-
-## Limits storage
-
-Limitador can store its limits and counters in-memory or in Redis. In-memory is
-faster, but the limits are applied per instance. When using Redis, multiple
-instances of Limitador can share the same limits, but it's slower.
-
+Refer to the help message on how to start up the server. More information are available
+in the [server's `README.md`](limitador-server/README.md)
 
 ## Development
 

doc/how-it-works.md

@@ -34,11 +34,11 @@ The counter's condition will match. Then, the counter will be increased and the
 If the limit is exceeded, the request will be rejected with `429 Too Many Requests`,
 otherwise accepted.
 
-Note that the counter is being activated eventhough it does not match *all* the entries of the
+Note that the counter is being activated even though it does not match *all* the entries of the
 descriptor. The same rule applies for the *variables* field.
 
-Currently *condition* implementation only allows *equal* operator.
-More operators can be implemented if there are use cases.
+Currently, the implementation of *condition* only allow for *equal* (`==`) and *not equal* (`!=`) operators.
+More operators will be implemented based off the use cases for them.
 
 The *variables* field is a list of keys.
 The matching rule is defined just as the existence of the list of descriptor entries with the
@@ -71,7 +71,7 @@ Reason: conditions key does not exist
 ```yaml
 conditions:
   - "KEY_A == 'VALUE_A'"
-  - "OTHER_KEY = 'WRONG_VALUE'"
+  - "OTHER_KEY == 'WRONG_VALUE'"
 max_value: 1
 seconds: 60
 variables: []

doc/migrations/conditions.md

@@ -0,0 +1,44 @@
+# New condition syntax 
+
+With `limitador-server` version `1.0.0` (and the `limitador` crate version `0.3.0`), the syntax for `condition`s within 
+`limit` definitions has changed.
+
+## Changes
+
+### The new syntax
+
+The new syntax formalizes what part of an expression is the identifier and which is the value to test against. 
+Identifiers are simple string value, while string literals are to be demarcated by single quotes (`'`) or double quotes
+(`"`) so that `foo == " bar"` now makes it explicit that the value is to be prefixed with a space character.
+
+A few remarks:
+ - Only `string` values are supported, as that's what they really are
+ - There is no escape character sequence supported in string literals
+ - A new operator has been added, `!=`
+
+### The issue with the deprecated syntax
+
+The previous syntax wouldn't differentiate between values and the identifier, so that `foo == bar` was valid. In this
+case `foo` was the identifier of the variable, while `bar` was the value to evaluate it against. Whitespaces before and
+after the operator `==` would be equally important. SO that `foo  ==  bar` would test for a `foo ` variable being equal
+to ` bar` where the trailing whitespace after the identifier, and the one prefixing the value, would have been
+evaluated.
+
+## Server binary users
+
+The server still allows for the deprecated syntax, but warns about its usage. You can easily migrate your limits file, 
+using the following command:
+
+```commandline
+limitador-server --validate old_limits.yaml > updated_limits.yaml
+```
+
+Which should output `Deprecated syntax for conditions corrected!` to `stderr` while `stdout` would be the limits using 
+the new syntax. It is recommended you manually verify the resulting `LIMITS_FILE`.
+
+
+## Crate users
+
+A feature `lenient_conditions` has been added, which lets you use the syntax used in previous version of the crate.
+The function `limitador::limit::check_deprecated_syntax_usages_and_reset()` lets you verify if the deprecated syntax 
+has been used as `limit::Limit`s are created with their condition strings using the deprecated syntax.