Skip to content

Latest commit

 

History

History
664 lines (521 loc) · 48.7 KB

CHANGELOG.md

File metadata and controls

664 lines (521 loc) · 48.7 KB
Raw

Couper Changelog

Unreleased

Unreleased changes are available as avenga/couper:edge container.

1.9.0

Couper 1.9 is a feature release bringing more comfort and enhanced stability to the Couper configuration. It also improves the permission handling and provides a couple of bug fixes. For a complete list of changes see below.

As of release 1.9 it is possible to split a Couper configuration into multiple .hcl-files. You can now, for example, use different configuration files for your api, files and definitions blocks, or keep your development, testing and production setups separated. All the configuration files given at startup will be merged together.

The new block beta_health (beta) allows you to configure recurring health check requests for a backend. By default, Couper won't request backends considered unhealthy which might help them recover due to the reduced amount of requests. The current health state of a backend can be accessed by variable. Changes in healthiness will be logged and exported as metrics.

To make permission handling easier to grasp we've dropped the term scope and accordingly changed the names of the beta_scope, beta_scope_claim and beta_scope_map attributes to beta_required_permission, beta_permissions_claim and beta_permissions_map, respectively. Furthermore, beta_required_permission (formerly beta_scope) can now be an HCL expression. If beta_required_permission is specified in both an endpoint and its parent api block, the former overrides the latter. Our permission handling examples illustrate some common use cases: basic example, roles example, map example

Along with this release goes the latest extension for VSCode which now indicates misplaced blocks and attributes, missing block labels and so on. We've also updated the completion suggestions and fixed a couple of syntax highlighting issues.

  • Added

    • Couper now reads and merges multiple configuration files (#437, #515)
    • beta_health-block to backend-block to enable continuous health-checks for defined backends (#313)
      • backends.<name>.health variable to access the current health-check state (subject to change)
    • Log malformed duration settings (#487)
    • url attribute could make use of our wildcard pattern /** and relative urls in combination with a backend reference (#480)
    • jwks_max_stale in jwt block (#502)
    • jwks_ttl, jwks_max_stale and configuration_max_stale in oidc block (#502)
    • Error handling for backend, backend_openapi_validation and backend_timeout error types (#490)
    • response.bytes log-field to backend logs if read from body, fallback is the Content-Length header (#494)
    • Error types endpoint and access_control (#500)

  • Changed

    • Permission handling: (#477, #504)
      • renamed beta_scope attribute for api and endpoint blocks to beta_required_permission; beta_required_permission in endpoint now overriding beta_required_permission in containing api block; allowing an expression as attribute value
      • renamed beta_scope_claim and beta_scope_map attributes for jwt block to beta_permissions_claim and beta_permissions_map
      • removed beta_operation_denied and beta_scope error types
      • renamed beta_insufficient_scope error type to beta_insufficient_permissions
      • added request.context.beta_required_permission and request.context.beta_granted_permissions request variables
    • Clarified the type of various attributes/variables (#485)
    • spa block can be defined multiple times now (#510)
    • files block can be defined multiple times now (#513)

  • Fixed

    • Keys in object type attribute values are only handled case-insensitively if reasonable (e.g. they represent HTTP methods or header field values) (#461)
    • Multiple labels for error_handler blocks (#462)
    • error_handler blocks for an error type defined in both endpoint and api (#469)
    • Request methods are treated case-insensitively when comparing them to methods in the allowed_methods attribute of api or endpoint blocks (#478)
    • Do not allow multiple backend blocks in proxy and request blocks (#483)
    • Panic if an error_handler block following another error_handler block has no label (#486)
    • Spurious duplicate endpoint /** error for APIs sharing the same base path (#507)
    • Invalid (by OpenAPI validation) backend response missing in backend_responses (#501)
    • Ignore the expected_status check for a request configured via a proxy or request block if a backend error occured (#505)
    • merge() function removes key with null value. (#518)

  • Removed

    • support for beta_oidc block (use oidc block instead) (#475)
    • support for beta_oauth_authorization_url and beta_oauth_verifier functions (use oauth2_authorization_url and oauth2_verifier functions instead) (#475)
    • path attribute from endpoint (and proxy) block; use path attribute in backend block instead (#516)

1.8.1

  • Fixed
    • missing error handling while loading a given ca_file (#460)
    • allow api blocks sharing the same base_path (#471)

1.8.0

  • Added

  • Changed

    • Automatically add the private directive to the response Cache-Control HTTP header field value for all resources protected by JWT (#418)

  • Fixed

    • improved protection against sniffing using unauthorized requests with non-standard method to non-existent endpoints in protected API (#441)
    • Couper handles OS-Signal INT in all cases in combination with the -watch argument (#456)
    • some error types related to JWT (#438)

1.7.2

  • Fixed
    • free up resources for backend response bodies without variable reference (#449)
    • Linux and Windows binary version output (CI) (#446)
    • error handling for empty error_handler labels (#432)

1.7.1

  • Fixed
    • missing upstream log field value for request.proto (#421)
    • handling of for loops in HCL (#426)
    • handling of conditionals in HCL: only predicates evaluating to boolean are allowed (#429)
    • broken binary on macOS Monterey; build with latest go 1.17.6 (ci) (#439)

1.7

We start 2022 with fresh release of Couper with some exciting features.

Our OpenID-Connect (OIDC) configuration specification has been proven as final and is moved out of beta to the oidc block. (Couper will still support beta_oidc until version 1.8). With OIDC, Couper supports a variety of Identity Provides such as Google, Azure AD, Keycloak and many more.

While microservices aim for decoupling, they still need to work together. A typical API gateway approach is to make them individually accessible and move the point of integration into the client. Couper sequences however allows you to chain requests in the gateway. The response of one service call is used as input for the request to the next service. This keeps coupling loose and inter-service connectivity robust. How Couper can help here is explained in our sequence example.

As part of our efforts to ease observability, Couper now allows you to collect custom log data. Use the custom_log_fields attribute all over your configuration file to augment your logs with information that is relevant to your application. Check out our example to find out how it works.

To further improve the developer experience with Couper the container image supports amd64 and arm64 architecture now. On top of that the binary installation has been improved for homebrew users: brew tap avenga/couper && brew install couper and go!

  • Added

  • Changed

    • oidc block is out of beta. (The beta_oidc block name will be removed with Couper 1.8. (#400)
    • oauth2_authorization_url() and oauth2_verifier() functions are our of beta. (The old function names beta_oauth_... will be removed with Couper 1.8). (#400)
    • The access control for the OIDC redirect endpoint (oidc block) now verifies ID token signatures (#404)
    • header = "Authorization" is now the default token source for JWT and may be omitted (#413)
    • Improved the validation for unique keys in all map-attributes in the config (#403)
    • Missing scope or roles claims, or scope or roles claim with unsupported values are now ignored instead of causing an error (#380)
    • Unbeta OIDC block. The old block name is still usable with Couper 1.7, but will no longer work with Couper 1.8. (#400)
    • Unbeta the oauth2_authorization_url() and oauth2_verifier() function. The prefix is changed from beta_oauth_... to oauth2_.... The old function names are still usable with Couper 1.7, but will no longer work with Couper 1.8. (#400)
    • Automatically add the private directive to the response Cache-Control HTTP header field value for all resources protected by JWT (#418)

  • Fixed

    • build-date configuration for binary and docker builds (#396)
    • exclude file descriptor limit startup-logs for Windows (#396, #383)
    • possible race conditions while updating JWKS for the JWT access control (#398)
    • panic while accessing primitive variables with a key (#377)
    • default() function continues to the next fallback value if this is a string type and an argument evaluates to an empty string (#408)
    • missing read of client-request bodies if related variables are used in referenced access controls only (e.g. JWT token source) (#415)

  • Dependencies

1.6

  • Added

    • Register default function as coalesce alias (#356)
    • New HCL function relative_url() (#361)
    • Log file descriptor limit at startup (#383)
    • error_handler block support for api and endpoint blocks (#317)
      • Enables reacting to additional error types: beta_scope, beta_insufficient_scope and beta_operation_denied
    • split() and substr() functions (#390)
    • hcl syntax verification for our configuration file (#296), (#168), (#188)
      • validate against the schema and additional requirements
      • available as verify command too

  • Changed

  • Fixed

    • Handling of accept_forwarded_url "host" if H-Forwarded-Host request header field contains a port (#360)
    • Setting Vary response header fields for CORS (#362)
    • Use of referenced backends in OAuth2 CC Blocks (#321)
    • CORS preflight requests are not blocked by access controls anymore (#366)
    • Reduced memory usage for backend response bodies which just get piped to the client and are not required to be read by Couper due to a variable references (#375)
      • However, if a huge message body is passed and additionally referenced via e.g. json_body, Couper may require a lot of memory for storing the data structure.
    • For each SAML attribute listed in array_attributes at least an empty array is created in request.context.<label>.attributes.<name> (#369)
    • HCL: Missing support for RelativeTraversalExpr, IndexExpr, UnaryOpExpr (#389)
    • HCL: Missing support for different variable index key types (#391)
    • OIDC: rejecting an ID token lacking an aud claim or with a null value aud (#393)

1.5

  • Added

  • Changed

    • Organized log format fields for uniform access and upstream log (#300)
    • claims in a jwt block are now evaluated per request, so that request properties can be used as required claim values (#314)
    • how Couper handles missing variables during context evaluation (#255)
      • Previously missing elements results in evaluation errors and expressions like set_response_headers failed completely instead of one key/value pair. The evaluation has two steps now and will look up variables first and prepares the given expression to return Nil as fallback.

  • Fixed

  • Beta

  • Dependencies

    • build with go 1.17 (#331)

1.4

Release date: 2021-08-26

This release introduces Beta Features. We use beta features to develop and experiment with new, complex features for you while still being able to maintain our compatibility promise. You can see beta features as a feature preview. To make users aware that a beta feature is used their configuration items are prefixed with beta_.

The first beta features incorporate the OAuth2 functionality into the Access Control capabilities of Couper. The beta_oauth2 {} block implements OAuth2 Authorization Code Grant Flows. The companion block beta_oidc {} implements OIDC, which allows simple integration of 3rd-party systems such as Google, Github or Keycloak for SSO (Single-Sign-On).

Together with transparent Websockets support that you can enable in your proxy {} block, you can guard existing Web applications with Couper via OIDC.

To aid observability of your setups, Couper sends its request ID as the Couper-Request-Id HTTP header in both backend requests and client responses. This makes it possible to trace events and correlate logs throughout the service chain. Couper can also accept a request ID generated by a downstream system like for example a load balancer. Like all settings, these can be configured in the config, as command line flag or via environment variables.

Load balancers or ingress services often provide X-Forwarded-Host headers. Couper can be configured to use these to change the properties of the request variable. This allows a Couper configuration to adapt to the run time environment, for example to create a back link for OIDC or SAML authorization requests with the request.origin variable.

If your applications are running in multiple setups, like testing and production environments, there will likely be more parameters that you want to have configurable. Backend origins, user names, credentials, timeouts, all that could be nice to be changed without a new deployment. Couper supports using environment variables with env.VAR-like expressions. Now, Couper can also provide default values for those variables. This makes it easy to have values configurable without the need to provide values outside of Couper (e.g. in Kubernetes). Our env vars example shows that in action.

1.3.1

  • Changed

    • Error log-level for upstream responses with status 500 to Info log-level (#258)

  • Fixed

    • Missing support for set_response_status within a plain error_handler block (#257)
    • Panic in jwt_sign() and saml_sso_url() functions without proper configuration (#243)

1.3

  • Added

    • Modifier (set/add/remove_form_params) for the form parameters (#223)
    • Modifier (set_response_status) to be able to modify the response HTTP status code (#250)

  • Changed

    • Stronger configuration check for path and path_prefix attributes, possibly resulting in configuration errors (#232)
    • Modifier (set/add/remove_response_headers) is available for api, files, server and spa block, too (#248)

  • Fixed

    • The path field in the backend log (#232)
    • Upstream requests with a known body-size have a Content-Length HTTP header field instead of Transfer-Encoding: chunked (#163)
    • Exit endpoint if an error is occurred in request or proxy instead of processing a defined response (#233)

1.2

Release date: 2021-05-19

The most important feature of Couper 1.2 is the introduction of custom error handling in form of the error_handler block. You can now register error handlers for error types. Instead of the standard error_file template, you can flexibly respond with arbitrary responses. error_handler is allowed in access control blocks (jwt, saml2 …), where you could e.g. handle missing tokens with a redirect-to-login. In the future, error_handler will be usable in more config areas. Refer to the example if you want to see it in action.

  • Added

    • error_handler block for access controls (#140)
    • backend_responses.*.body variable for accessing raw response body content (#182)
    • more oauth2 config options: scope and token_endpoint_auth_method (client_secret_basic or client_secret_post) (#219, #220)

  • Changed

    • saml2 fallback to nameid-format:unspecified (#217)
    • basic_auth always responds with status code 401 (#227)
    • openapi resolves relative server URLs to the current backend origin (#230)

  • Fixed

    • Fix /healthz route when called with accept-encoding: gzip (#222)
    • Don't panic over duplicate access control definitions, log error instead (#221)
    • Response for missing routes should have status code 404 (#224)
    • Fix possible race-condition with concurrent openapi validations (#231)
    • Fix use of server URLs without port in openapi (#230)

1.1.1

Release date: 2021-04-21

  • Fixed
    • Endpoint responses are written and logged with correct status-code (#216)
      • affected: a plain response without any additional headers or body configuration

1.1

Release date: 2021-04-16

  • Fixed

    • allow more +json mime types (#207)
      • determines if ja request/response body gets parsed and provided as json_body variable
    • missing check for empty endpoint path patterns (#211)
    • protected API (base)paths returns status 401 instead of 404 if a protected route was not found (#211)
    • jwt source config definition (#210)
    • missing inner context on context copy
    • possible panic for unhandled error template write errors (#205)
    • backend reference usage with string label (#189)
    • cli argument filtering (#204)
    • misleading jwt rsa key error (#203)
    • watch handling on stat errors (#202)

  • Changed

    • Change access control validation logging (#199)
      • log the first occurred error instead of an array

  • Added

    • Add OAuth2 token request retry option (#167) (#209)

1.0

Release date: 2021-04-09

  • Added

    • couper help and usage documentation (#187)

  • Changed

    • Ensure unique keys for set_* and add_* attributes (#183)
    • split docker entrypoint and command (#192)

  • Fixed

    • Fix missing backend.origin attribute url validation (#191)

0.9

Release date: 2021-04-08

  • Fixed

    • Log option for json formatted logs: (#176)
      • configured parent key applies to (almost) all log fields

  • Changed

    • Change variable names to more user-friendly ones (#180):
      • req -> request
      • ctx -> context
      • bereq -> removed
      • beresp -> removed
      • bereqs -> backend_requests
      • beresps -> backend_responses
    • Log option for parent fields are 'global' now (#176)
      • COUPER_ACCESS_LOG_PARENT_FIELD, COUPER_BACKEND_LOG_PARENT_FIELD -> COUPER_LOG_PARENT_FIELD

  • Added

    • watch option for given Couper configuration file (#24)
      • use -watch or via environment COUPER_WATCH=true to watch for file changes
    • log option pretty print for json log-format (#179)
      • -log-pretty to enable formatted and key colored logs

0.8

Release date: 2021-04-06

  • Fixed

    • Some possible race conditions in combination with multiple proxy and/or request definitions are fixed (#157) (#160)
    • Log endpoint related recovered panics
    • CORS behaviour: result is now only dependent on the config, not the actual request; fixed Vary headers (#173)
    • Fix json type assumption (#177)
      • req.json_body result is an empty object for specific types (#165)
      • Empty json array encodes to null. (#162)
    • Fix missing string conversion for evaluated number values (#175)
    • Loading optional labels of same type
    • multiplexer behaviour with multiple servers and hosts (#161)
    • Fix missing access_control for file handler (#169)
    • 404 behaviour for access controlled endpoints: deny instead of 404 if the request matches the related base_path (#143)

  • Changed

    • Rename log type for backend requests: couper_upstream -> couper_backend (#159) (#172)
    • Rename post variable to form_body (#158)

  • Added

    • Add json_body attribute for request and response block (#158)
    • bytes log field to represent the body size

0.7.0

Release date: 2021-03-23

  • Fixed

    • Recover from possible request/proxy related panics (#157) (#145)
    • Configuration related hcl merge with an empty attributes and nested blocks

  • Changed

    • backend block attributes basic_auth, path_prefix and proxy hcl evaluation during runtime
    • request attributes hcl evaluation during runtime (#152)
    • Change configuration in combination with URL and backend.origin (#144)
      • request and proxy block can use the url attribute instead of define or reference a backend
      • same applies to oauth2.token_endpoint
    • no X-Forwarded-For header enrichment from couper proxy (#139)
    • more log context for access control related errors (#154)

  • Added

    • saml 2.0 access_control support (#113)
    • Add new strip-secure-cookies setting (#147)
      • removes Secure flag from all Set-Cookie header
    • CORS support (server, files, spa) (#134)
      • previously api only
    • error_file attribute for endpoint block
    • hcl functions:
      • merge
      • url_encode
    • backend
      • OAuth2 support (#130)
        • grant_type: client_credentials
        • token memory storage with ttl
      • path_prefix attribute (#138)

0.6.1

Release date: 2021-03-15

  • Fixed

    • Fix missing panic recovering for backend roundtrips (#142)
      • Fix backend timeout behaviour
      • Add a more specific error message for proxy body copy errors

  • Changed

    • Couper just passes the X-Forwarded-For header if any instead of adding the client remote addr to the list (#139)

  • Added

    • url_encode function for RFC 3986 string encoding (#136)

0.6

Release date: 2021-03-11

  • Breaking Change
    • backend will be consumed by proxy and request as transport configuration now. The previous behaviour that backend represents a proxy functionality is removed. Also the backend block must be defined in definitions, proxy or request.
      • Config migration, add a proxy block:
endpoint "/old" {
  backend = "reference"
  # or
  backend {
    #...
  }
}
# change to:
endpoint "/new" {
  proxy {
    backend = "reference"
  }
  # or
  proxy {
    backend {
      #...
    }
  }
}

  • Changed

    • Client-Request and upstream response body buffering by default
    • Server shutdown delay and deadline defaults to 0s now and can be configured via env if required
    • Websocket connection upgrades in combination with proxy {} are disabled
      • we will add a proxy option for ws usage later on

  • Fixed

    • An absolute path resolving for *_file configuration attributes (#120)

  • Added

    • Endpoint:
      • Add proxy block to reverse proxy the client request to the configured backend.
      • Add request block to send a simple upstream request. Docs
      • Add response block to create a custom client response. Docs
    • Add jwt_sign() function to be able to create and sign a token with a jwt_signing_profile. Docs (#112)
    • Add unixtime() function for the current unix time in seconds (#124)

  • Code Refactoring

    • underlying code structure to represent an endpoint block with proxy, request and response configuration
    • hcl evaluation context as own 'container' with context.Context interface
    • test cleanups

  • Dependencies

    • build with go 1.16
    • logrus to v1.8.1
    • hcl to v2.9.1
    • kin-openapi to v.0.49.0

0.5.1

Release date: 2021-02-16

  • Added

    • backend:
      • a user-friendly basic_auth option
      • backend proxy url, disable_connection_reuse and http2 settings (#108)
    • version command

  • Changed

    • KeepAlive 60s (#108), previously 15s
    • Reject requests which hits an endpoint with basic-auth access-control, and the configured password evaluates to an empty string (#115)

0.5

Release date: 2021-01-29

  • Fixed

    • Fix missing http.Hijacker interface to be able to handle websocket upgrades (#80)

  • Added

    • Add additional eval functions: coalesce, json_decode, json_encode (#105)
    • Add multi API support (#103)
    • Add free endpoints (#90)
    • Add remove_, set_ and add_headers (#98)

  • Code Refactoring

    • improved internals for configuration load

  • Dependencies

    • Upgrade hcl to 2.8.2
    • Upgrade go-cty module to 1.5.0
    • Upgrade logrus module to 1.7.0
    • Upgrade kin-openapi module to v0.37

0.4.2

Release date: 2021-01-19

  • Fixed
    • Fix used backend hash not dependent on (hcl) config hierarchy (transport key)
    • Fix logging http scheme even without a successful tls handshake (#99)
    • Fix hcl.Body content for reference backends (#96)

0.4.1

Release date: 2021-01-18

  • Fixed
    • Fix path trailing slash (#94)
    • Fix query encoding (#93)
    • Fix log_format (settings) configuration (#61)

0.4

Release date: 2021-01-13

  • Added

    • url log field (#87)
    • Add proxy from env settings option (#84)
    • Add backend settings: disable_certificate_validation, max_connections (#86)

  • Fixed

    • command flag filter for bool values (#85)
    • different proxy options for same origin should be part of the origin transport key

  • Code Refactoring

    • configuration load and prepare related body merges on hcl level

0.3

Release date: 2020-12-15

  • Added

    • build version to startup log
    • upstream request/response validation with openapi (#21) (#22)
    • request-id: uuid v4 format option #31 (#53)
    • path_params #59
    • gzip support (#66)
    • query_params (#73)
    • json_body access for request and response bodies #44 (#60)

  • Changed

    • start Couper via run command now
    • internal router #59
    • docker tag behaviour on release #70 (#82)
    • request/response_headers to use set prefix (#77)
    • passing the filename to underlying hcl diagnostics
    • Dockerfile to provide simple file serving (#63)

  • Fixed

    • handling cty null or unknown values during roundtrip eval #71
    • logging: start-time measurement
    • missing backend.hostname documentation (#62)

0.2

Release date: 2020-10-08

  • Added

    • health check (#29)
    • Basic-Auth support (#19)
    • post (form) parsing for use in config variables (#26)
    • more documentation

  • Fixed

    • wildcard path join with trailing slash and respect req path (#45)
    • env var mapping (#35)
    • JWT HMAC keys (#32)

0.1

Release date: 2020-09-11

  • Added
    • Parse and load from given HCL configuration file
    • Config structs for blocks: server, api, endpoint, files, spa, definitions, jwt
    • HTTP handler implementation for api backends, files, spa and related config mappings
    • CORS handling for api endpoints
    • Access control configuration for all blocks
    • Access control type jwt with claim validation
    • Access und backend logs
    • Configurable error templates with a fallback to our defaults
    • Github actions for our continuous integration workflows
    • Dockerfile
    • Documentation