Update proxy configuration format (#144)

* Update proxy configuration

Update proxy configuration format
Update tests and docs
Merge the server/client configuration example
Replace metrics config with generic admin config

Fixes #130

Co-authored-by: Mark Mandel <markmandel@google.com>

Cargo.toml

@@ -41,6 +41,7 @@ warp = "0.2.3"
 base64 = "0.12.3"
 base64-serde = "0.5.1"
 tonic = "0.3"
+uuid = {version = "0.8.1", default-features = false, features = ["v4"]}
 
 [dev-dependencies]
 reqwest = "0.10.6"

docs/extensions/filters/capture_bytes.md

@@ -16,21 +16,21 @@ quilkin.extensions.filters.capture_bytes.v1alpha1.CaptureBytes
 ### Configuration Examples
 ```rust
 # let yaml = "
-local:
-  port: 7000
-filters:
-  - name: quilkin.extensions.filters.capture_bytes.v1alpha1.CaptureBytes
-    config:
-        strategy: PREFIX
-        metadataKey: myapp.com/myownkey
-        size: 3
-        remove: false
-client:
-  addresses:
-    - 127.0.0.1:7001
+version: v1alpha1
+static:
+  filters:
+    - name: quilkin.extensions.filters.capture_bytes.v1alpha1.CaptureBytes
+      config:
+          strategy: PREFIX
+          metadataKey: myapp.com/myownkey
+          size: 3
+          remove: false
+  endpoints:
+    - name: server-1
+      address: 127.0.0.1:7001
 # ";
 # let config = quilkin::config::Config::from_reader(yaml.as_bytes()).unwrap();
-# assert_eq!(config.filters.len(), 1);
+# assert_eq!(config.source.get_filters().len(), 1);
 # quilkin::proxy::Builder::from(std::sync::Arc::new(config)).validate().unwrap();
 ```
 
@@ -70,4 +70,4 @@ properties:
 
 * `quilkin_filter_CaptureBytes_packets_dropped`  
   A counter of the total number of packets that have been dropped due to their length being less than the configured
-  `size`.
+  `size`.

docs/extensions/filters/concatenate_bytes.md

@@ -11,19 +11,19 @@ quilkin.extensions.filters.concatenate_bytes.v1alpha1.ConcatenateBytes
 ### Configuration Examples
 ```rust
 # let yaml = "
-local:
-  port: 7000
-filters:
-  - name: quilkin.extensions.filters.concatenate_bytes.v1alpha1.ConcatenateBytes
-    config:
-        strategy: APPEND
-        bytes: MXg3aWp5Ng==
-client:
-  addresses:
-    - 127.0.0.1:7001
+version: v1alpha1
+static:
+  filters:
+    - name: quilkin.extensions.filters.concatenate_bytes.v1alpha1.ConcatenateBytes
+      config:
+          strategy: APPEND
+          bytes: MXg3aWp5Ng==
+  endpoints:
+    - name: server-1
+      address: 127.0.0.1:7001
 # ";
 # let config = quilkin::config::Config::from_reader(yaml.as_bytes()).unwrap();
-# assert_eq!(config.filters.len(), 1);
+# assert_eq!(config.source.get_filters().len(), 1);
 # quilkin::proxy::Builder::from(std::sync::Arc::new(config)).validate().unwrap();
 ```
 

docs/extensions/filters/debug.md

@@ -12,18 +12,18 @@ quilkin.extensions.filters.debug_filter.v1alpha1.Debug
 ### Configuration Examples
 ```rust
 # let yaml = "
-local:
-  port: 7000
-filters:
-  - name: quilkin.extensions.filters.debug.v1alpha1.Debug
-    config:
-      id: debug-1
-client:
-  addresses:
-    - 127.0.0.1:7001
+version: v1alpha1
+static:
+  filters:
+    - name: quilkin.extensions.filters.debug.v1alpha1.Debug
+      config:
+        id: debug-1
+  endpoints:
+    - name: server-1
+      address: 127.0.0.1:7001
 # ";
 # let config = quilkin::config::Config::from_reader(yaml.as_bytes()).unwrap();
-# assert_eq!(config.filters.len(), 1);
+# assert_eq!(config.source.get_filters().len(), 1);
 # quilkin::proxy::Builder::from(std::sync::Arc::new(config)).validate().unwrap();
 ```
 

docs/extensions/filters/filters.md

@@ -33,23 +33,23 @@ There are a few things we note here:
 
 ```rust
 # let yaml = "
-local:
-  port: 7000
-filters:
-  - name: quilkin.extensions.filters.debug_filter.v1alpha1.Debug
-    config:
-      id: debug-1
-  - name: quilkin.extensions.filters.local_rate_limit.v1alpha1.LocalRateLimit
-    config:
-      max_packets: 10
-      period: 500ms
-client:
-  addresses:
-    - 127.0.0.1:7001
+version: v1alpha1
+static:
+  filters:
+    - name: quilkin.extensions.filters.debug_filter.v1alpha1.Debug
+      config:
+        id: debug-1
+    - name: quilkin.extensions.filters.local_rate_limit.v1alpha1.LocalRateLimit
+      config:
+        max_packets: 10
+        period: 500ms
+  endpoints:
+    - name: server-1
+      address: 127.0.0.1:7001
 # ";
 # let config = quilkin::config::Config::from_reader(yaml.as_bytes()).unwrap();
 # assert_eq!(config.validate().unwrap(), ());
-# assert_eq!(config.filters.len(), 2);
+# assert_eq!(config.source.get_filters().len(), 2);
 ```
 
 We specify our filter chain in the `.filters` section of the proxy's configuration which has takes a sequence of [FilterConfig](#filter-config) objects. Each object describes all information necessary to create a single filter.

docs/extensions/filters/load_balancer.md

@@ -12,18 +12,18 @@ quilkin.extensions.filters.load_balancer.v1alpha1.LoadBalancer
 # #[tokio::main]
 # async fn main() {
 #   let yaml = "
-local:
-  port: 7000
-filters:
-  - name: quilkin.extensions.filters.load_balancer.v1alpha1.LoadBalancer
-    config:
-      policy: ROUND_ROBIN
-client:
-  addresses:
-    - 127.0.0.1:7001
+version: v1alpha1
+static:
+  filters:
+    - name: quilkin.extensions.filters.load_balancer.v1alpha1.LoadBalancer
+      config:
+        policy: ROUND_ROBIN
+  endpoints:
+    - name: server-1
+      address: 127.0.0.1:7001
 # ";
 #   let config = quilkin::config::Config::from_reader(yaml.as_bytes()).unwrap();
-#   assert_eq!(config.filters.len(), 1);
+# assert_eq!(config.source.get_filters().len(), 1);
 #   quilkin::proxy::Builder::from(std::sync::Arc::new(config)).validate().unwrap();
 # }
 ```

docs/extensions/filters/local_rate_limit.md

@@ -12,19 +12,19 @@ quilkin.extensions.filters.local_rate_limit.v1alpha1.LocalRateLimit
 # #[tokio::main]
 # async fn main() {
 #   let yaml = "
-local:
-  port: 7000
-filters:
-  - name: quilkin.extensions.filters.local_rate_limit.v1alpha1.LocalRateLimit
-    config:
-      max_packets: 1000
-      period: 500ms
-client:
-  addresses:
-    - 127.0.0.1:7001
+version: v1alpha1
+static:
+  filters:
+    - name: quilkin.extensions.filters.local_rate_limit.v1alpha1.LocalRateLimit
+      config:
+        max_packets: 1000
+        period: 500ms
+  endpoints:
+    - name: server-1
+      address: 127.0.0.1:7001
 # ";
 #   let config = quilkin::config::Config::from_reader(yaml.as_bytes()).unwrap();
-#   assert_eq!(config.filters.len(), 1);
+# assert_eq!(config.source.get_filters().len(), 1);
 #   quilkin::proxy::Builder::from(std::sync::Arc::new(config)).validate().unwrap();
 # }
 ```
@@ -57,4 +57,4 @@ required: [ 'max_packets' ]
 ### Metrics
 
 * `quilkin_filter_LocalRateLimit_packets_dropped`  
-  A counter over the total number of packets that have exceeded the configured maximum rate limit and have been dropped as a result.
+  A counter over the total number of packets that have exceeded the configured maximum rate limit and have been dropped as a result.

docs/extensions/filters/token_router.md

@@ -14,13 +14,12 @@ quilkin.extensions.filters.token_router.v1alpha1.TokenRouter
 ### Configuration Examples
 ```rust
 # let yaml = "
-local:
-  port: 7000
-filters:
-  - name: quilkin.extensions.filters.token_router.v1alpha1.TokenRouter
-    config:
-        metadataKey: myapp.com/myownkey
-server:
+version: v1alpha1
+static:
+  filters:
+    - name: quilkin.extensions.filters.token_router.v1alpha1.TokenRouter
+      config:
+          metadataKey: myapp.com/myownkey
   endpoints: 
     - name: Game Server No. 1
       address: 127.0.0.1:26000
@@ -33,7 +32,7 @@ server:
         - bmt1eTcweA==
 # ";
 # let config = quilkin::config::Config::from_reader(yaml.as_bytes()).unwrap();
-# assert_eq!(config.filters.len(), 1);
+# assert_eq!(config.source.get_filters().len(), 1);
 # quilkin::proxy::Builder::from(std::sync::Arc::new(config)).validate().unwrap();
 ```
 
@@ -76,15 +75,14 @@ For example, a configuration would look like:
 
 ```rust
 # let yaml = "
-local:
-  port: 7000
-filters:
-  - name: quilkin.extensions.filters.capture_bytes.v1alpha1.CaptureBytes # Capture and remove the authentication token
-    config:
-        size: 3
-        remove: true
-  - name: quilkin.extensions.filters.token_router.v1alpha1.TokenRouter
-server:
+version: v1alpha1
+static:
+  filters:
+    - name: quilkin.extensions.filters.capture_bytes.v1alpha1.CaptureBytes # Capture and remove the authentication token
+      config:
+          size: 3
+          remove: true
+    - name: quilkin.extensions.filters.token_router.v1alpha1.TokenRouter
   endpoints: 
     - name: Game Server No. 1
       address: 127.0.0.1:26000
@@ -97,9 +95,9 @@ server:
         - bmt1eTcweA==
 # ";
 # let config = quilkin::config::Config::from_reader(yaml.as_bytes()).unwrap();
-# assert_eq!(config.filters.len(), 2);
+# assert_eq!(config.source.get_filters().len(), 2);
 # quilkin::proxy::Builder::from(std::sync::Arc::new(config)).validate().unwrap();
 ```
 
 On the game client side the [ConcatenateBytes](./concatenate_bytes.md) filter could also be used to add authentication
-tokens to outgoing packets.
+tokens to outgoing packets.

docs/proxy-configuration.md

@@ -0,0 +1,81 @@
+Proxy Configuration
+
+The following is the schema and reference for a Quilkin proxy configuration file. See the [examples] folder for example configuration files.
+
+```yaml
+type: object
+properties:
+  version:
+    type: string
+    description: |
+      The configuration file version to use.
+    enum:
+      - v1alpha1
+  proxy:
+    type: object
+    description: |
+      Configuration of core proxy behavior.
+    properties:
+      id:
+        type: string
+        description: |
+          An identifier for the proxy instance.
+        default: <uuid> A unique ID is generated for the proxy.
+      port:
+        type: integer
+        description: |
+          The listening port for the proxy.
+        default: 7000
+      mode:
+      type: string
+      description: |
+        The mode in which the proxy should run.
+      enum:
+        - SERVER
+        - CLIENT
+      default: SERVER
+  admin:
+    type: object
+    description: |
+      Configuration of operational proxy behavior.
+    properties:
+      metrics:
+      type: object
+      description: |
+        Metrics related configuration.
+      properties:
+        port:
+          type: integer
+          description: |
+            Port on which to expose metrics.
+          default: 9091
+  static:
+    type: object
+    description: |
+      Static configuration of endpoints and filters.
+    properties:
+      filter:
+        '$ref': '#/definitions/filterchain'
+      endpoints:
+        '$ref': '#/definitions/endpoints'
+    required:
+      - endpoints
+
+required:
+  - version
+
+definitions:
+  filterchain:
+    type: array
+    description: |
+      A filter chain.
+    items:
+      '$ref': {} # Refer to the Filter documentation for a filter configuration schema.
+  endpoints:
+    type: array
+    description: |
+      A list of upstream endpoints to forward packets to.
+```
+
+[examples]: ../examples
+