From 017904ad8e44bbde2412fcc2da3df0ab582c9297 Mon Sep 17 00:00:00 2001 From: Evgeny Abramovich Date: Sat, 20 May 2023 10:54:54 -0300 Subject: [PATCH] Update README.md --- README.md | 191 ++++++++++-------------------------------------------- 1 file changed, 33 insertions(+), 158 deletions(-) diff --git a/README.md b/README.md index d664449d..2d561a40 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,15 @@

- A simple dev HTTP/HTTPS proxy for replacing CORS headers. + A simple dev HTTP/HTTPS proxy for replacing CORS headers.

- - Go version - - - GitHub version - + + Go version + + + GitHub version + License @@ -37,14 +37,16 @@ # Core features - CORS header replacement -- HTTPS support -- Wildcard URL request mapping -- Simple request/response mocking +- Wildcard host mapping +- [HTTPS support](https://github.com/evg4b/uncors/wiki/2.-Configuration#https-support) +- [Request/response mocking](https://github.com/evg4b/uncors/wiki/3.-Response-mocksing) - HTTP/HTTPS proxy support -- Static file serving +- [Static file serving](https://github.com/evg4b/uncors/wiki/4.-Static-file-serving) - *Response caching ([coming soon...](./ROADMAP.md))* -Other new features you can find in [UNCORS roadmap](https://github.com/evg4b/uncors/blob/main/ROADMAP.md) +Other new features you can find in [roadmap](https://github.com/evg4b/uncors/blob/main/ROADMAP.md) + +Full documentation you can found on [wiki pages](https://github.com/evg4b/uncors/wiki). # Quick Install @@ -82,6 +84,22 @@ Via yarn: yarn add uncors --dev ``` +## Docker + +We currently offer images for [Docker](https://hub.docker.com/r/evg4b/uncors) + +```bash +docker run -p 80:3000 evg4b/uncors --from 'http://local.github.com' --to 'https://github.com' +``` + +## Stew (Cross-platform) + +Also you can install binaris using [Stew](https://github.com/marwanhawari/) with the following commands: + +```bash +stew install evg4b/uncors +``` + ## Binary (Cross-platform) Download the appropriate version for your platform @@ -91,14 +109,6 @@ This works well for shared hosts and other systems where you don’t have a priv Ideally, you should install it somewhere in your `PATH` for easy use. `/usr/local/bin` is the most probable location. -## Docker - -We currently offer images for [Docker](https://hub.docker.com/r/evg4b/uncors) - -```bash -docker run -p 80:3000 evg4b/uncors --from 'http://local.github.com' --to 'https://github.com' -``` - ## Build from source **Prerequisite Tools** @@ -123,145 +133,10 @@ If you are a Windows user, substitute the $HOME environment variable above with # Usage -The following command can be used to start the Uncors proxy server: +The following command can be used to start the UNCORS proxy server: ``` -uncors --http-port 8080 --to 'https://github.com' --from 'http://localhost' -``` - -## CLI Parameters - -The following command-line parameters can be used to configure the Uncors proxy server: - -* `--from` - Specifies the local host with protocol for the resource from which proxying will take place. -* `--to` - Specifies the target host with protocol for the resource to be proxied. -* `--http-port` or `-p` - Specifies the local HTTP listening port. -* `--https-port` or `-s` - Specifies the local HTTPS listening port. -* `--cert-file` - Specifies the path to the HTTPS certificate file. -* `--key-file` - Specifies the path to the matching certificate private key. -* `--proxy` - Specifies the HTTP/HTTPS proxy to provide requests to the real server (system default is used by default). -* `--config` - Specifies the path to the [configuration file](#configuration-file). -* `--debug` - Enables debug output. - -Any configuration parameters passed via CLI (except for `--from` and `--to`) will override the corresponding -parameters specified in the configuration file. The `--from` and `--to` parameters will add an additional mapping -to the configuration. - -## Configuration file - -Uncors supports a YAML file configuration with the following options: - -```yaml -# Base configuration -http-port: 8080 # Local HTTP listened port. -mappings: - - http://localhost: https://githib.com - - from: http://other.domain.com - to: https//example.com - statics: - /path: ./public - /another-path: ~/another-static-dir -debug: false # Show debug output. -proxy: localhost:8080 - -# HTTPS configuration -https-port: 8081 # Local HTTPS listened port. -cert-file: ~/server.crt # Path to HTTPS certificate file. -key-file: ~/server.key # Path to matching for certificate private key. - -# Mock definitions are used to generate fake responses for certain endpoints. -mocks: - - path: /hello-word - response: - code: 200 - raw-content: 'Hello word' +uncors --from 'http://localhost' --to 'https://github.com' --http-port 8080 ``` -#### Mocks configuration - -The mocks configuration section in Uncors allows you to define specific endpoints to be mocked, including the response -data and other parameters. Currently, mocks are defined globally for all mappings. Available path, method, queries, and headers filters, -which utilize the [gorilla/mux route matching system](https://github.com/gorilla/mux#matching-routes). - -Each endpoint mock requires a path parameter, which defines the URL path for the endpoint. You can also use the method -parameter to define a specific HTTP method for the endpoint. - -The queries and headers parameters can be used to specify more detailed URLs that will be mocked. The queries parameter -allows you to define specific query parameters for the URL, while the headers parameter allows you to define specific -HTTP headers. - -Here is the structure of the mock configuration: - -```yaml -mocks: - - path: - method: - queries: - : - # ... - headers: - : - # ... - response: - code: - headers: - : - # ... - delay: - raw-content: - file: -``` - -- `path` (required) - This property is used to define the URL path that should be mocked. The value should be a string, - such as `/example`. The path can include variables, such as `/users/{id}`, which will match any URL that starts - with `/users/` and has a variable `id` in it. -- `method` (optional) - This property is used to define the HTTP method that should be mocked. - The value should be a string. If this property is not specified, the mock will match any HTTP method. -- `queries` (optional) - This property is used to define specific query parameters that should be matched against the - request URL. The value should be a mapping of query parameters and their values, such as `{"param1": "value1", " - param2": "value2"}`. If this property is not specified, the mock will match any query parameter. -- `headers` (optional): This property is used to define specific HTTP headers that should be matched against the request - headers. The value should be a mapping of header names and their values, such as `{"Content-Type": "application/json"}`. - If this property is not specified, the mock will match any HTTP header. -- `response` (required): This property is used to define the mock response. It should be a mapping that contains the - following properties: - - `code` (optional): This property is used to define the HTTP status code that should be returned in the mock - response. The value should be an integer, such as 200 or 404. If this property is not specified, the mock will use - 200 OK status code. - - `headers` (optional): This property is used to define specific HTTP headers that should be returned in the mock - response. The value should be a mapping of header names and their values, such as `{"Content-Type": " - application/json"}`. If this property is not specified, the mock response will have no extra headers. - - `delay` (optional): This property is used to define a delay before sending the mock response. The value should be a - string in the format ` ...`, where `` is a positive integer and `` is time units. - Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `1m 30s` would delay the response by 1 minute and 30 - seconds. If this property is not specified, the mock response will be sent immediately. - - `raw-content` (optional): This property is used to define the raw content that should be returned in the mock - response. The value should be a string, such as `Hello, world!`. If this property is not specified, the mock - response will be empty. - - `file` (optional): This property is used to define the path to a file that contains the mock response content. The - file content will be used as the response content. The value should be a string that specifies the file path, such - as `~/mocks/example.json`. If this property is not specified, the mock response will be empty. - -## How it works - -```mermaid -sequenceDiagram - participant Client - participant Uncors - participant Server - - - alt Handling OPTIONS queries - Client ->> Uncors: Access-Control-Request - Uncors ->> Client: Allow-Control-Request - end - - alt Handling Data queries - Client ->> Uncors: GET, POST, PUT... query - Note over Uncors: Replacing url with target
in headers and cookies - Uncors-->>Server: Real GET, POST, PUT... query - Server->>Uncors: Real response - Note over Uncors: Replacing url with source
in headers and cookies - Uncors-->>Client: Data response - end -``` +More information about configuration and usage you can fiund on [UNCORS wiki](https://github.com/evg4b/uncors/wiki). \ No newline at end of file