2. Configuration

UNCORS can be configured in two ways: by passing CLI arguments or by using a configuration file. Parameters passed via CLI arguments are more important and will override the configuration specified in the config file.

The main idea behind UNCORS is to define host mappings for converting local domains defined in the host file to real domains on the internet. Based on this concept, the configuration can be split into two levels: 'global configuration properties' and 'mapping configuration properties'. Global configuration properties affect all mappings and configure the base server behavior, while mapping configuration properties only configure the response that will be provided in accordance with the mapping.

СLI options

The UNCORS proxy server can be configured using the following command-line parameters:

Mappings Configuration

--from or -f - Specifies the local host with protocol for the resource from which proxying will take place.

--to or -t - Specifies the target host with protocol for the resource to be proxy.

These parameters can be passed multiple times as a pair to define new mappings or add additional ones to the configuration file.

Global Configuration

--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 use for requests to the real server (the system default is used by default).

--config - Specifies the path to the configuration file.

--debug - Enables debug output.

Any configuration parameters passed via the command-line interface will override the corresponding parameters specified in the configuration file.

Configuration file overview

UNCORS supports a YAML file configuration with the following options:

# global configuration
http-port: 80
debug: false
proxy: localhost:8080
https-port: 443
cert-file: ~/server.crt
key-file: ~/server.key

# mappings configuration
mappings:
  - http://localhost: https://githib.com
  - from: http://other.domain.com
    to: https//example.com
    statics:
      /path: ./public
      /another-path: ~/another-static-dir
    mocks:
      - path: /hello
        response:
          code: 200
          delay: 1m 30s
          raw-content: "Hello word"
      - path: /word
        method: POST
        response:
          code: 203
          delay: 5s
          file: ./path/to/file.data

Global Configuration

http-port - The local port on which the HTTP server listens (default: 80).

https-port - The local port on which the HTTPS server listens (default: 443).

cert-file - Path to the HTTPS certificate file.

key-file - Path to the private key file that matches the certificate.

proxy - URL of the HTTP/HTTPS proxy

debug - Indicates whether to display debug output (default: false).

mappings - A list of mappings that describe how to forward requests. See more below.

Mappings Configuration

The config file includes a mappings section that describes how UNCORS should forward requests. Each mapping item consists of a from and to host pair with the scheme, using the following syntax:

mappings:
  - from: http://localhost
    to: https://githib.com
    mocks: [...]
    statics: [...]

In this example, requests sent to http://localhost will be forwarded to https://github.com. Additionally, you can configure mocks and static file serving for these requests. For more information on configuring mocks, please refer to the relevant section: Mocks configuration. Similarly, for static file serving configuration, please refer to: Static file serving configuration.

Scheme mapping

An important part of mappings is the ability to redirect requests from one scheme to another. UNCORS can redirect requests from http to https, from https to http, or use the original request scheme.

To configure mappings from http to https or from https to http, you simply need to specify the correct scheme in the mapping:

mapping:
  - from: http://localhost
    to: https://site.com

or

mapping:
  - from: https://localhost
    to: http://site.com

If you specify // as the scheme, it will match any scheme.

You can redirect any request to a specific scheme (e.g., https) by using // as the scheme:

mapping:
  - from: //localhost
    to: https://site.com

Alternatively, you can use the original request scheme by setting both hosts to //:

mapping:
  - from: //localhost
    to: //site.com

Note: To work with the https scheme, you need to configure a certificate. Refer to HTTPS configuration for more details.

Wildcard mapping

UNCORS provides support for wildcard matching in host mappings. The * character can be used to match any number of characters except for . and /. This allows you to redirect requests from multiple domains or implement template mapping.

Let's look at a few examples:

mappings:
  - from: http://*.local.com
    to: https://githib.com

In this example, all requests with the *.local.com subdomain will be redirected to https://github.com. Here are some examples to illustrate this:

Local request	Target request
http://raw.local.com	https://githib.com
http://raw.local.com/api/info	https://githib.com/api/info
http://docs.local.com	https://githib.com
http://docs.local.com/index.html	https://githib.com/index.html

Another example:

mappings:
  - from: http://*.local.com
    to: https://*.github.com

In this case, the * in the source host will be replaced with the corresponding value from the * in the target host. Here are some additional examples:

Local request	Target request
http://raw.local.com	https://raw.githib.com
http://raw.local.com/api/info	https://raw.githib.com/api/info
http://docs.local.com	https://docs.githib.com
http://docs.local.com/index.html	https://docs.githib.com/index.html

You can also use multiple * characters in a mapping. In this case, they will be replaced in the order in which they appear.

Short syntax

If you don't need request mocking or file serving, you can use a short syntax for mappings in your configuration file ( wildcard also supports):

mappings:
  - http://localhost: https://githib.com

You can mix mappings the simplified syntax with the full definition format based on your specific requirements for each mapping entry.

mappings:
  - http://localhost: https://githib.com
  - http://host1: https://gitlab.com
  - http://*.com: https://*.io
  - from: http://host2
    to: https://gitea.com
    mocks: [...]
    statics: [...]

Warning

Remember that matching with urals only works if the addressable domain is added in the hosts file. This means that mappings like https://* will not intercept all requests, but only those specified in the hosts file.

HTTPS configuration

UNCORS provides HTTPS support, allowing you to define mappings for requests originating from https:// URLs, enabling forwarding to either https:// or http:// destinations.

To operate the HTTPS server, you'll need an authorized certificate. It supports self-signed certificates. You must have the cert.key and cert.crt files for the certificate. Refer to the provided instructions for guidance on creating the certificate.

In the configuration file, specify the following properties for HTTPS:

https-port: 8443
cert-file: ~/path/to/cert.crt
key-file: ~/path/to/cert.key

To set up mappings with the local host, you can include the https:// or // scheme. Here's an example:

mappings:
  - https://localhost: https://githib.com
  # OR
  - //localhost': //github.com

Note: If you don't set up mappings with a scheme that includes the https protocol, the HTTPS certificates won't be used.

Proxy configuration

UNCORS automatically use your system proxy defined in ENV variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY). The environment values may be either a complete URL or a host[:port], in which case the http scheme is assumed.

In addition, the proxy address can be set explicitly using the --proxy command line parameter or the proxy global property in the configuration file.

Config scheme

UNCORS provides JSON Schema for validating configuration files. Validation will automatically be available in all editors that support the SchemaStore API.

However, you can manually configure JSON Schema mappings for your IDE or code editor.

JetBrains IDE's

Go to Settings -> Languages & Frameworks -> Schemas and DTDs -> JSON Schema Mappings.

Add a new JSON Schema Mapping with name Uncors Config Schema and next params.

• Schema file or URL: https://raw.githubusercontent.com/evg4b/uncors/main/schema.json
• Schema version: JSON Schema version 4
• File paths patterns: *.uncors.yml, *.uncors.yaml, .uncors.yml, .uncors.yaml

VS Code

Go to User Settings -> Extenstions -> JSON -> JSON:Schemas and click Edit in settings.json.

In opened file add in sectionjson.schemas next code:

{
  "fileMatch": ["*.uncors.yml", "*.uncors.yaml", ".uncors.yml", ".uncors.yaml"],
  "url": "https://raw.githubusercontent.com/evg4b/uncors/main/schema.json"
}

Other

For configuring other IDEs and editors, use the following parameters:

• Schema URL: https://raw.githubusercontent.com/evg4b/uncors/main/schema.json
• Schema version: JSON Schema version 4
• File paths patterns: *.uncors.yml, *.uncors.yaml, .uncors.yml, .uncors.yaml