API7 Gateway 3.9.16

Release Date: 2026-07-10

Upgrade Notes

Features

Plugins

• AI Cache (opens in Plugin Hub docs) (new plugin)
  • Caches LLM responses in Redis so repeated prompts can be served without calling the upstream model again. It supports exact-match caching, optional semantic (L2) matching through embeddings and RediSearch, streaming response caching and replay, configurable bypass rules, and Prometheus metrics for cache hits, misses, bypasses, and embedding latency.
• AI Lakera Guard (opens in Plugin Hub docs) (new plugin)
  • Screens AI traffic through the Lakera Guard API to detect prompt injection and other unsafe content. The direction option (input, output, or both) selects whether the plugin scans request prompts, LLM responses (including streaming responses), or both. Flagged traffic is blocked with a configurable deny_code, or only logged when action is set to alert.
• AI Aliyun Content Moderation (opens in Plugin Hub docs)
  • Added request_check_roles to choose which request roles are moderated (user, tool, and/or system). user and tool content follow request_check_mode (last or all, default last), while system content is checked on every request when selected. Long content is now split into chunks in linear time and is multi-byte (UTF-8) safe.
• AI AWS Content Moderation (opens in Plugin Hub docs)
  • Request moderation now runs after AI protocol detection and checks the decoded prompt content that the upstream LLM sees, rather than the raw HTTP JSON envelope. Deny responses are returned in a provider-compatible format, with configurable check_request, deny_code, and deny_message.
• Elasticsearch Logger (opens in Plugin Hub docs)
  • Added support for authenticating to Elasticsearch with custom request headers via the headers option, for example an Authorization: Bearer <token> or API-key header, as an alternative or complement to basic auth.
• Rate-limiting plugins
  • Added Redis connection keepalive settings (redis_keepalive_timeout and redis_keepalive_pool) for the Redis and Redis Cluster policies in Limit Count (opens in Plugin Hub docs), Limit Count Advanced (opens in Plugin Hub docs), GraphQL Limit Count (opens in Plugin Hub docs), and AI Rate Limiting (opens in Plugin Hub docs), so operators can tune idle timeout and connection pool size.

Data Plane

• Added apisix.trusted_addresses, which controls whether the gateway trusts client-supplied X-Forwarded-* and Forwarded headers based on the resolved client address.
• Added apisix.match_uri_encoded_slash. When enabled, an encoded slash (%2F) stays encoded during route matching so it can be treated as part of a path parameter instead of a path separator.
• Added apisix.max_post_args_readable_size (default 64 MiB), which bounds how much JSON or multipart request body data is read when matching post_arg.* route predicates. Set it to 0 to disable the limit.
• In standalone YAML mode, environment-variable placeholders are now resolved before YAML parsing. Unquoted placeholders can become native booleans or numbers, while quoted placeholders stay strings, preserving large IDs and token values exactly.

Control Plane

• Added TOTP two-factor authentication for built-in Dashboard users. Users can enroll, enable, disable, and recover 2FA from their account settings, and administrators can reset a user's 2FA state.
• Added login failure restriction for built-in users. Repeated failed logins temporarily lock the user and source IP, emit an audit event, and return a clear lockout message.
• Added the Dashboard UI for two-factor authentication: account setup with QR code and recovery codes, an OTP step during login, and an administrator action to reset a user's 2FA state.
• Updated password forms and generated passwords to use the new 12-character minimum length.

Fixes

Plugins

• AI Proxy (opens in Plugin Hub docs) and AI Proxy Multi (opens in Plugin Hub docs)
  • Fixed issue: Anthropic Messages requests that contained tool results mixed with other content could be converted into an invalid OpenAI Chat message order, causing OpenAI-compatible upstreams to reject every later request in the session. Tool messages are now emitted immediately after the assistant tool-call message, and adjacent text or media is preserved in a following user message.
  • Fixed issue: Several Anthropic-to-OpenAI conversion details diverged from LiteLLM-compatible behavior, including tool name sanitization, long tool-name collision handling, adaptive thinking effort, structured-output schema extraction, empty array encoding, and content block shaping.
  • Fixed issue: Structured chat content could reach downstream AI plugins as a table and cause request processing errors. Protocol adapters now flatten text content consistently before AI guard and cache plugins consume it.
  • Fixed issue: A failure while constructing the ai-proxy-multi working instance pool could raise a Lua error and destructively clear pool state. The failure path is now nil-safe and non-destructive.
• gRPC Transcode (opens in Plugin Hub docs)
  • Fixed issue: Empty protobuf repeated fields were encoded as {} instead of JSON arrays ([]). Empty repeated fields now appear as arrays, including nested and descriptor-set based messages.
• Key Auth (opens in Plugin Hub docs) and other consumer authentication plugins
  • Fixed issue: If a consumer credential referenced a secret that could not be resolved, the Data Plane could still index the unresolved literal value and authenticate requests with it. Consumer authentication now fails closed when a referenced secret cannot be resolved.
• Secret references
  • Fixed issue: Updates or deletions of /secrets configuration did not invalidate the secret LRU cache, so old secret values could continue to be used until cache expiry or indefinitely. Secret references are now re-resolved after secret configuration changes.
• Proxy Rewrite (opens in Plugin Hub docs)
  • Fixed issue: With use_real_request_uri_unsafe and uri configured together, the request query string was dropped during URI rewriting. The original query string is now preserved and correctly merged when the rewritten URI already contains a query.
• Loggly
  • Fixed issue: Batched Loggly entries from different routes could use the wrong token or tags because the async handler reused the latest route configuration. Each batch processor now keeps its own route configuration.
• Datadog (opens in Plugin Hub docs)
  • Fixed issue: Large coalesced DogStatsD datagrams could exceed the common 8192-byte agent buffer and be silently truncated. The plugin now coalesces only when the payload fits, otherwise it falls back to one datagram per metric.
• Zipkin (opens in Plugin Hub docs)
  • Fixed issue: Requests explicitly marked as unsampled still built full span tag tables and access-phase child spans. Unsampled requests now skip that extra tracing work while preserving trace propagation.
• OpenTelemetry (opens in Plugin Hub docs)
  • Fixed issue: Updating OpenTelemetry plugin metadata at runtime did not rebuild the tracer used for injected core spans, so those spans could keep using stale collector or resource settings until worker recycle. The tracer now refreshes when metadata changes.
  • Fixed issue: additional_attributes were evaluated before log-phase variables were populated, so attributes that depend on final request state could be missing or stale. They are now evaluated in the log phase.
• OpenID Connect (opens in Plugin Hub docs)
  • Fixed issue: refresh_session_interval incorrectly defaulted to 900, enabling silent re-authentication even when users did not configure it. The default is removed (see Upgrade Notes).
• MQTT Proxy (opens in Plugin Hub docs)
  • Fixed issue: protocol_name was required even though the standard default is MQTT. It is now optional and defaults to MQTT.
• Forward Auth (opens in Plugin Hub docs)
  • Fixed issue: When request_method was POST, the authorization request could forward the client's Transfer-Encoding, Content-Length, and Expect headers after the body had already been buffered, producing inconsistent request framing. These client framing headers are no longer copied to the auth service.
• Authz CASBIN
  • Fixed issue: Routes using different Casbin model or policy shapes could trigger casbin enforce error / invalid request size after switching between them. The bundled lua-casbin dependency is updated to include the enforcement fixes.
• AI Aliyun Content Moderation (opens in Plugin Hub docs)
  • Fixed issue: Returning ngx.OK from the body filter could interrupt later body-filter processing. The plugin now returns normally so other filters can continue.
• Request ID (opens in Plugin Hub docs)
  • Fixed issue: Configuring algorithm: range_id without the optional range object could return HTTP 500. The range object now has a default value.
• Workflow (opens in Plugin Hub docs)
  • Fixed issue: Workflow action plugins could run _meta.pre_function hooks before workflow skipped or executed the action, changing behavior even for actions that should not run. Workflow now decides whether to run the action before executing those meta hooks.
• Redirect
  • Fixed issue: http_to_https only redirected requests whose scheme was exactly http, so a request arriving with a non-HTTP, non-HTTPS scheme, for example through a forged X-Forwarded-Proto, was not redirected. It now redirects every non-HTTPS scheme.
• Response Rewrite (opens in Plugin Hub docs)
  • Fixed issue: When the upstream response was compressed (gzip or brotli), filters were applied to the compressed bytes and did not match, producing a corrupted body. The response is now decoded before filters run.
• Batch Requests
  • Fixed issue: When a pipelined sub-request timed out, the response array could contain more entries than there were sub-requests. The number of sub-responses now always matches the number of sub-requests.
• Tencent Cloud CLS
  • Fixed issue: With include_req_body enabled, the request body was not captured because it was not read in the access phase. The body is now read so that it is included in uploaded logs when sampling allows it.
• Attach Consumer Label (opens in Plugin Hub docs)
  • Fixed issue: A client could spoof a configured header when the matched Consumer had no labels, because the plugin overwrote the header only when a label value was present. Configured headers are now always stripped from the client request, even when the Consumer has no matching label.
• Authz Keycloak (opens in Plugin Hub docs)
  • Fixed issue: With lazy_load_paths enabled, the request query string was included when resolving the Keycloak resource by URI, so requests with query parameters could fail to match the intended resource. The query string is now stripped before resolution.
• CAS Auth
  • Fixed issue: The CAS single-logout (SLO) callback POST was proxied to the upstream instead of being handled by the plugin. The callback is now terminated by the plugin and is no longer forwarded upstream.
• gRPC Web (opens in Plugin Hub docs)
  • Fixed issue: A debug log statement wrote the decoded request body to the error log. The statement has been removed so request payloads are no longer leaked into logs.

Data Plane

• Fixed issue: Log rotation could leave some log files open after only part of the file set was rotated. The gateway now reopens logs correctly after partial rotation.
• Fixed issue: Environment-variable substitution in configuration directives could match the wrong variable when one variable name was a prefix of another. Names are now resolved exactly.
• Fixed issue: After a transient DNS or service-discovery failure, a domain-name upstream could remain stuck returning HTTP 503 even after the name resolved again. The upstream now recovers once resolution succeeds.
• Fixed issue: Upgraded the Prometheus metrics library (nginx-lua-prometheus-api7 to 0.20260623) to remove duplicate metric series that could cause a scrape to be rejected.

Control Plane

• Fixed issue: Gateway instances could be marked OutOfSync for a short window immediately after a configuration revision changed, before the next heartbeat reported the new revision. A grace period now keeps recently heartbeating instances Healthy during that normal synchronization window.
• Fixed issue: Compatibility reports were capped at 200 unordered items, so large reports could hide errors and differ between gateway instances. The Control Plane now stores the full sorted report and computes compatibility from all items.
• Fixed issue: A secret provider request body could match a different provider type than the provider named in the URL path, causing the Data Plane to discard or misread the stored secret. The Control Plane now validates the body against the selected provider type.
• Fixed issue: The Control Plane accepted some core resource configurations that the Data Plane silently discarded, including invalid TLS, filter, and IP match configurations. These are now rejected by validation before publishing.
• Fixed issue: IPv6 upstream node hosts were rejected by the OpenAPI schema. IPv6 hosts are now accepted.
• Fixed issue: Batch ssls validation used the SNI schema instead of the SSL schema, so entries without required certificate fields could pass validation. Batch SSL validation now uses the correct schema.
• Fixed issue: Audit log export returned only the first 256 rows. Exports now include all matching audit logs.
• Fixed issue: Credential lookup indexes could be dropped by components that do not run database migration, and some startup schema repairs rebuilt current indexes unnecessarily. Schema repair now keeps current indexes and repairs only stale shapes.
• Fixed issue: Heartbeat and instance status queries could become slow on large deployments. Additional indexes and Go-side status computation improve these lookups.