Skip to content

Commit 4709746

Browse files
VeinarVeinar
committed
Added docs on how to configure Dracan
1 parent 8acf938 commit 4709746

File tree

3 files changed

+344
-0
lines changed

3 files changed

+344
-0
lines changed

‎.dockerignore

+4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
tests/*
2+
docs/*
3+
example/*
24
*pycache*
35
[I|i]nclude
46
[L|l]ib
57
[S|s]cripts
68
pyvenv.cfg
9+
pytest.ini
10+
Dockerfile
711
# Uncomment this for real case scenario, because this files should be provided by user
812
#proxy_config.json
913
#rules_config.json

‎docs/proxy_config.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# `proxy_config.json` Configuration Guide
2+
3+
This short doc will explain how to set properly proxy config file.
4+
5+
```json
6+
{
7+
"destination": {
8+
"host": "127.0.0.1",
9+
"port": 8080,
10+
"path": "/"
11+
}
12+
}
13+
```
14+
15+
**Explanation of Fields:**
16+
17+
* **host**: The IP address or hostname or FQDN of the target server where requests should be forwarded. In this example, it’s set to `127.0.0.1` (localhost) but on real case scenario it would rather look like `application.namespace.svc.cluster.local`.
18+
* **port**: The port on the target server where the application listens.
19+
* **path**: The base path on the destination server to which requests should be forwarded. Using `/` as the path will forward requests to the root of the target server.

‎docs/rules_config.md

+321
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
# `rules_config.json` Configuration Guide
2+
3+
This short doc will explain how to set properly proxy config file.
4+
5+
**Note:** By default if `*_enabled` is not specified inside configuration file validation/limiting will be **disabled**.
6+
7+
**Table of contents:**
8+
9+
1. Time limits (rate limits)
10+
2. HTTP Method validation
11+
3. URI Path validation
12+
4. Payload size limiting
13+
5. JSON schema validation
14+
6. Header validation
15+
16+
## 1. Time limits (rate limits)
17+
18+
`limiting_enabled`
19+
20+
Description: *Enables or disables rate limiting.*
21+
Possible values: *`true` or `false`*
22+
23+
Example:
24+
```json
25+
...
26+
"limiting_enabled": true
27+
...
28+
```
29+
30+
`rate_limit`
31+
32+
Description: *Specifies the allowed rate of requests*
33+
Possible values: *[LINK](https://github.com/alisaifee/flask-limiter?tab=readme-ov-file#inspect-the-limits-using-the-command-line-interface)*
34+
35+
Example:
36+
```json
37+
...
38+
"rate_limit": "20 per minute"
39+
...
40+
```
41+
or
42+
```json
43+
...
44+
"rate_limit": "10 per second"
45+
...
46+
```
47+
48+
## 2. HTTP Method validation
49+
50+
`method_validation_enabled`
51+
52+
Description: *Enables validation of HTTP request methods.*
53+
Possible values: *`true` or `false`*
54+
55+
Example:
56+
```json
57+
...
58+
"method_validation_enabled": true
59+
...
60+
```
61+
> If not set tp `true`, Dracan will allow only `["GET", "OPTION", "POST", "PUT", "DELETE"]` methods.
62+
63+
`rate_limit`
64+
65+
Description: *Specifies HTTP methods allowed for incoming requests.*
66+
Possible values: *array of methods (even single method should be passed as an array)*
67+
68+
Example:
69+
```json
70+
...
71+
"allowed_methods": ["GET", "UPDATE", "POST", "PUT", "DELETE"]
72+
...
73+
```
74+
or
75+
```json
76+
...
77+
"allowed_methods": ["GET", "POST"]
78+
...
79+
```
80+
81+
## 3. URI Path validation
82+
83+
`method_validation_enabled`
84+
85+
Description: *Enables validation of URI paths for incoming requests.*
86+
Possible values: *`true` or `false`*
87+
88+
Example:
89+
```json
90+
...
91+
"uri_validation_enabled": true
92+
...
93+
```
94+
95+
`allowed_uris`
96+
97+
Description: *Specifies **exact** URIs that are allowed.*
98+
Possible values: *array of exact allowed URIs (even single URI should be passed as an array)*
99+
100+
Example:
101+
```json
102+
...
103+
"allowed_uris": ["/health", "/data", "/update", "/delete"]
104+
...
105+
```
106+
or
107+
```json
108+
...
109+
"allowed_uris": ["/", "/person"]
110+
...
111+
```
112+
113+
`allowed_uri_patterns`
114+
115+
Description: *Uses regular expressions to allow URIs matching specific patterns.*
116+
Possible values: *array of allowed URIs patterns (even single URI should be passed as an array)*
117+
118+
Example:
119+
```json
120+
...
121+
"allowed_uri_patterns": ["^/api/.*", "^/public/[A-Za-z0-9_-]+"]
122+
...
123+
```
124+
or
125+
```json
126+
...
127+
"allowed_uri_patterns": ["^/[A-Za-z0-9_-]+"]
128+
...
129+
```
130+
131+
> Regexp must comply with python `re`.
132+
133+
## 4. Payload limiting
134+
135+
`payload_limiting_enabled`
136+
137+
Description: *Enables size limitations for request payloads.*
138+
Possible values: *`true` or `false`*
139+
140+
Example:
141+
```json
142+
...
143+
"payload_limiting_enabled": true
144+
...
145+
```
146+
147+
`max_payload_size`
148+
149+
Description: *Sets the maximum size (in bytes) allowed for a request payload.*
150+
Possible values: *any integer value*
151+
152+
Example:
153+
```json
154+
...
155+
"max_payload_size": 1024
156+
...
157+
```
158+
or
159+
```json
160+
...
161+
"max_payload_size": 8388608 //This will be 8 MB
162+
...
163+
```
164+
165+
## 5. JSON Schema Validation
166+
167+
`json_validation_enabled`
168+
169+
Description: *Enables validation for JSON bodies in requests.*
170+
Possible values: *`true` or `false`*
171+
172+
Example:
173+
```json
174+
...
175+
"json_validation_enabled": true
176+
...
177+
```
178+
179+
`json_schema`
180+
181+
Description: *Defines the expected JSON structure using a JSON schema, enforcing data types and required fields.*
182+
Possible values: *constructed JSON schema*
183+
184+
Example:
185+
```json
186+
...
187+
"json_schema": {
188+
"type": "object",
189+
"properties": {
190+
"name": { "type": "string" },
191+
"age": { "type": "number" }
192+
},
193+
"required": ["name", "age"]
194+
}
195+
...
196+
```
197+
Explanation: *Schema requires name as a string and age as a number. Any JSON payload not meeting these criteria will be rejected.*
198+
199+
or
200+
201+
```json
202+
...
203+
"json_schema": {
204+
"type": "object",
205+
"properties": {
206+
"user": {
207+
"type": "object",
208+
"properties": {
209+
"name": {
210+
"type": "string"
211+
},
212+
"address": {
213+
"type": "object",
214+
"properties": {
215+
"street": {
216+
"type": "string"
217+
},
218+
"city": {
219+
"type": "string"
220+
},
221+
"zip": {
222+
"type": "integer"
223+
}
224+
},
225+
"required": [
226+
"street",
227+
"city"
228+
]
229+
}
230+
},
231+
"required": [
232+
"name",
233+
"address"
234+
]
235+
}
236+
}
237+
}
238+
...
239+
```
240+
241+
Explanation: *Allows for nested properties, enforcing that user has name and an address object.*
242+
243+
or
244+
245+
```json
246+
"json_schema" = {
247+
"type": "object",
248+
"properties": {
249+
"products": {
250+
"type": "array",
251+
"items": {
252+
"type": "object",
253+
"properties": {
254+
"id": {
255+
"type": "integer"
256+
},
257+
"name": {
258+
"type": "string"
259+
},
260+
"price": {
261+
"type": "number"
262+
}
263+
},
264+
"required": [
265+
"id",
266+
"name",
267+
"price"
268+
]
269+
}
270+
}
271+
}
272+
}
273+
```
274+
275+
Explanation: Requires a list of products, each with specific properties.
276+
277+
## 6. Header validation
278+
279+
`header_validation_enabled`
280+
281+
Description: *Enables validation of HTTP request headers.*
282+
Possible values: *`true` or `false`*
283+
284+
Example:
285+
```json
286+
...
287+
"header_validation_enabled": true
288+
...
289+
```
290+
291+
`required_headers`
292+
293+
Description: *Defines headers that must be included in the request. Supports exact matches, wildcard (just checking if present), and regular expressions.*
294+
Possible values: *array of exact allowed headers (even single header should be passed as an array)*
295+
296+
Example:
297+
```json
298+
...
299+
"required_headers": {
300+
"Content-Type": "application/json",
301+
"X-API-KEY": "*", //This is wildcard (so, Dracan will check only if header is present)
302+
"Authorization": "regex:^Bearer\\s[A-Za-z0-9\\-_]+\\.[A-Za-z0-9\\-_]+\\.[A-Za-z0-9\\-_]+$"
303+
},
304+
...
305+
```
306+
> Make note, that `regex:` keyword is used for validating against regular expression. Do not omit this keyword in order to use functionality.
307+
308+
`prohibited_headers`
309+
310+
Description: *Defines headers that should not be included in requests.*
311+
Possible values: *array of allowed URIs patterns (even single URI should be passed as an array)*
312+
313+
Example:
314+
```json
315+
...
316+
"prohibited_headers": [
317+
"X-Internal-Header",
318+
"X-Debug-Token"
319+
]
320+
...
321+
```

0 commit comments

Comments
 (0)