Skip to content

Migration Guide

Jump to bottom
github-actions edited this page May 15, 2026 · 7 revisions

This guide helps you migrate your UNCORS configuration files when upgrading between versions. Breaking changes are documented with before/after examples.

Table of Contents

Version 0.5.x to 0.6.x

This is a major version with several breaking changes. Review all three sections before upgrading.

TLS Certificate Configuration Changes

Breaking Change: Global cert-file and key-file configuration properties have been removed from the root level. TLS certificates must now use auto-generated certificates with a local CA.

Why This Change?

The previous architecture required all HTTPS mappings to share the same certificate. The new approach uses auto-generated certificates with a local CA, providing greater flexibility, SNI support, and simpler configuration.

Migration Steps

Old Configuration (v0.5.x and earlier):

cert-file: ~/certs/server.crt
key-file: ~/certs/server.key
mappings:
  - from: https://app.local:8443
    to: https://api.example.com
  - from: https://admin.local:8443
    to: https://admin.example.com

New Configuration (v0.6.x):

mappings:
  - from: https://app.local:8443
    to: https://api.example.com
  - from: https://admin.local:8443
    to: https://admin.example.com

Before using HTTPS mappings, generate a local CA once:

uncors generate-certs

This creates ~/.config/uncors/ca.crt. Add this certificate to your system's trusted certificates to avoid browser warnings.

Key Changes:

  1. Remove the global cert-file and key-file properties
  2. Run uncors generate-certs to create a local CA
  3. Trust the CA certificate in your system's certificate store

Benefits of Auto-Generated Certificates

  • Automatic certificate generation for any host
  • No need to manage certificate files
  • SNI (Server Name Indication) support - multiple hosts on the same port
  • Certificates cached in memory, regenerated only when needed

Port Configuration Changes

Breaking Change: Global http-port and https-port configuration properties have been removed. Ports are now specified directly in the mapping URLs.

Why This Change?

The previous architecture required all HTTP mappings to share the same port and all HTTPS mappings to share the same port. The new per-mapping port configuration allows each mapping to listen on its own port.

Migration Steps

Old Configuration (v0.5.x and earlier):

http-port: 8080
https-port: 8443
mappings:
  - from: http://localhost
    to: https://api.example.com
  - from: https://secure-app
    to: https://backend.example.com

New Configuration (v0.6.x):

mappings:
  - from: http://localhost:8080
    to: https://api.example.com
  - from: https://secure-app:8443
    to: https://backend.example.com

Key Changes:

  1. Remove the global http-port and https-port properties
  2. Add the port number directly to the from URL: protocol://host:port
  3. Ports default to 80 for HTTP and 443 for HTTPS when omitted

Multiple Ports Example

The new architecture enables each mapping to use a different port:

mappings:
  - from: http://api.local:3000
    to: https://api.example.com
  - from: http://admin.local:4000
    to: https://admin.example.com
  - from: https://secure.local:8443
    to: https://backend.example.com

Short Syntax Migration

Old:

http-port: 8080
mappings:
  - http://localhost: https://github.com

New:

mappings:
  - http://localhost:8080: https://github.com

Command-Line Arguments Migration

Old:

uncors --http-port 8080 --from http://localhost --to https://api.example.com

New:

uncors --from http://localhost:8080 --to https://api.example.com

Wildcard Mapping Migration

Old:

http-port: 8080
mappings:
  - from: http://*.local.com
    to: https://*.example.com

New:

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

Fake Response Feature Removal

Breaking Change: The fake field for generating mock responses with fake data has been removed. Use Lua script handlers instead for dynamic response generation.

Why This Change?

The Lua script handler provides a more flexible and powerful way to generate dynamic responses. It allows for complex logic, external command execution, and better maintainability.

Migration Steps

Old Configuration (v0.5.x and earlier):

mappings:
  - from: http://localhost:8080
    to: https://api.example.com
    mocks:
      - path: /api/users
        response:
          code: 200
          fake:
            type: object
            properties:
              login:
                type: email
              username:
                type: username
          seed: 12345

New Configuration (v0.6.x) - Using Script Handler:

mappings:
  - from: http://localhost:8080
    to: https://api.example.com
    scripts:
      - path: /api/users
        script: |
          local handle = io.popen("fakedata --format=ndjson --limit 1 login=email username=username")
          local output = handle:read("*a")
          handle:close()

          response.headers["Content-Type"] = "application/json"
          response:WriteHeader(200)
          response:WriteString(output)

Key Changes:

  1. Remove the mocks section with fake and seed properties
  2. Add a scripts section with a Lua script handler
  3. Use the fakedata CLI tool or any other tool of your choice

Installing fakedata

macOS:

brew install lucapette/tap/fakedata

Linux/macOS with Go:

go install github.com/lucapette/fakedata@latest

Example: Array of Objects

Old:

response:
  code: 200
  fake:
    type: array
    item:
      type: object
      properties:
        name:
          type: name
        email:
          type: email
    count: 5

New:

scripts:
  - path: /api/users
    script: |
      local handle = io.popen("fakedata --format=ndjson --limit 5 name=name email=email")
      local output = handle:read("*a")
      handle:close()

      -- Convert NDJSON to JSON array
      local lines = {}
      for line in output:gmatch("[^\n]+") do
          table.insert(lines, line)
      end
      local result = "[" .. table.concat(lines, ",") .. "]"

      response.headers["Content-Type"] = "application/json"
      response:WriteHeader(200)
      response:WriteString(result)

Advantages of the Script Handler Approach

  • More flexible: Execute any command-line tool, not just fake data generation
  • Better control: Use Lua logic for complex data transformations
  • External tools: Leverage fakedata, faker-cli, or custom scripts
  • Full language: Access to Lua's complete capabilities for complex scenarios

For more information, see the Script Handler documentation.

Need Help?

If you encounter issues during migration:

  1. Check the Configuration documentation for the current format
  2. Review the JSON Schema for configuration validation
  3. Enable debug mode: uncors --config .uncors.yaml --debug
  4. Report issues at GitHub Issues

Clone this wiki locally