v1.9.1

1.9.1

• Fixed
  • missing environment key-error while using multiple configuration files (#522)

v1.9.0

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)

v1.8.1

1.8.1

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

v1.8.0

1.8.0

• Added

  • disable_private_caching attribute for the JWT Block (#418)
  • backend_request and backend_response variables (#430)
  • beta_scope_map attribute for the JWT Block (#434)
  • saml error type (#424)
  • allowed_methods attribute for the API or Endpoint Block (#444)
  • new HCL functions: contains(), join(), keys(), length(), lookup(), set_intersection(), to_number() (#455)
  • ca_file option to settings (also as argument and environment option) (#447)
    • Option for adding the given PEM encoded ca-certificate to the existing system certificate pool for all outgoing connections.

• 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-existant 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)

Grafana Dashboard
We have updated the grafana.json, see https://github.com/avenga/couper/blob/master/docs/METRICS.md#preview for a screenshot.

v1.7.2

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)

v1.7.1

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

v1.7.0

1.7

We start 2022 with a 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

  • Support for sequences of outgoing endpoint requests (#405)
  • expected_status attribute for request and proxy block definitions which can be caught with error handling (#405)
  • custom_log_fields attribute to be able to describe a user defined map for custom log field enrichment (#388)
  • jwt block/jwt_signing_profile block support ECDSA signatures (#401)
  • user as context variable from a Basic Auth is now accessible via request.context.<label>.user for successfully authenticated requests (#402)

• 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)

• 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

  • Update kin-openapi used for OpenAPI validation to v0.83.0 (#399)

1.6

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

  • server block label is now optional, api block may be labelled (#358)
  • Timings in logs are now numeric values (#367)

• 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

1.5

• Added

  • Accept: application/json request header to the OAuth2 token request, in order to make the Github token endpoint respond with a JSON token response (#307)
  • Documentation of logs (#310)
  • signing_ttl and signing_key/signing_key_file to jwt block for use with jwt_sign() function (#309)
  • jwks_url and jwks_ttl to jwt block (#312)
  • token_value attribute in jwt block (#345)
  • headers attribute in jwt_signing_profile block (#329)

• 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

  • Key for storing and reading OpenID configuration (#319)

• Beta

  • beta_scope_claim attribute to jwt block; beta_scope attribute to api and endpoint blocks; error types beta_operation_denied and beta_insufficient_scope (#315)
  • beta_roles_claim and beta_roles_map attributes to jwt block (#325) (#338) (#352)
  • Metrics: Prometheus exporter (#295)

• Dependencies

  • build with go 1.17 (#331)

1.4

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 enviroment, 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.

• Added

  • environment_variables map in the defaults block to define default values for environment variables (#271)
  • https-dev-proxy option creates a TLS server listing on the given TLS port. Requests are forwarded to the given server port. The certificate is generated on-the-fly. This function is intended for local development setups to support browser features requiring HTTPS connections, such as secure cookies. (#281)
  • websockets option in proxy block enables transparent websocket support when proxying to upstream backends (#198)
  • Client request variables request.url, request.origin, request.protocol, request.host and request.port (#255)
  • Run option -accept-forwarded-url and setting accept_forwarded_url to accept proto, host, or port from X-Forwarded-Proto, X-Forwarded-Host or X-Forwarded-Port request headers (#255)
  • Couper sends its request ID as Couper-Request-Id HTTP header in backend requests and client responses. This can be configured with the request_id_backend_header and request_id_client_header settings (#268)
  • request_id_accept_from_header setting configures Couper to use a downstream request ID instead of generating its own in order to help correlating log events accross services (#268)
  • couper.version variable (#274)
  • protocol, host, port, origin, body, json_body to backend_requests variable (#278)
  • Locking to avoid concurrent requests to renew OAuth2 Client Credentials access tokens (#270)

• Changed

  • The sp_acs_url in the SAML Block may now be relative (#265)

• Fixed

  • No GZIP compression for small response bodies (#186)
  • Missing error type for request/response body, json_body or form_body related HCL evaluation errors (#276)
  • request.url and backend_requests.<label>.url now contain a query string if present (#278)
  • backend_responses.<label>.status is now integer (#278)
  • backend_requests.<label>.form_body was always empty (#278)
  • Documentation of request.query.<name> (#278)
  • Missing access log on some error cases (#267)
  • Panic during backend origin / url usage with previous parse error (#206)
  • Basic Auth did not work if only the htpasswd_file attribute was defined (#293)
  • Missing error handling for backend gzip header reads (#291)
  • ResponseWriter fallback for possible statusCode 0 writes (#291)
  • ResponseWriter buffer behaviour; prepared chunk writes (#301)
  • Proper client-request canceling (#294)

• Beta

  • OAuth2 Authorization Code Grant Flow: beta_oauth2 {} block; beta_oauth_authorization_url() and beta_oauth_verifier() (#247)
  • OIDC Authorization Code Grant Flow: beta_oidc {} block (#273)