// Copyright 2025 Envoy Project Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
//     http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package envoy.extensions.filters.http.lua.v3;

import "envoy/config/core/v3/base.proto";

import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";

import "envoy/annotations/deprecation.proto";
import "udpa/annotations/status.proto";
import "udpa/annotations/versioning.proto";
import "validate/validate.proto";

option java_package = "io.envoyproxy.envoy.extensions.filters.http.lua.v3";
option java_outer_classname = "LuaProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/lua/v3;luav3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Lua]
// Lua :ref:`configuration overview <config_http_filters_lua>`.
// [#extension: envoy.filters.http.lua]

// [#next-free-field: 6]
message Lua {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.http.lua.v2.Lua";

  // The Lua code that Envoy will execute. This can be a very small script that
  // further loads code from disk if desired. Note that if JSON configuration is used, the code must
  // be properly escaped. YAML configuration may be easier to read since YAML supports multi-line
  // strings so complex scripts can be easily expressed inline in the configuration.
  //
  // This field is deprecated. Please use
  // :ref:`default_source_code <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.default_source_code>`.
  // Only one of :ref:`inline_code <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.inline_code>`
  // or :ref:`default_source_code <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.default_source_code>`
  // can be set for the Lua filter.
  string inline_code = 1
      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

  // Map of named Lua source codes that can be referenced in :ref:`LuaPerRoute
  // <envoy_v3_api_msg_extensions.filters.http.lua.v3.LuaPerRoute>`. The Lua source codes can be
  // loaded from inline string or local files.
  //
  // Example:
  //
  // .. code-block:: yaml
  //
  //   source_codes:
  //     hello.lua:
  //       inline_string: |
  //         function envoy_on_response(response_handle)
  //           -- Do something.
  //         end
  //     world.lua:
  //       filename: /etc/lua/world.lua
  //
  map<string, config.core.v3.DataSource> source_codes = 2;

  // The default Lua code that Envoy will execute. If no per route config is provided
  // for the request, this Lua code will be applied.
  config.core.v3.DataSource default_source_code = 3;

  // Optional additional prefix to use when emitting statistics. By default
  // metrics are emitted in *.lua.* namespace. If multiple lua filters are
  // configured in a filter chain, the stats from each filter instance can
  // be emitted using custom stat prefix to distinguish emitted
  // statistics. For example:
  //
  // .. code-block:: yaml
  //
  //   http_filters:
  //     - name: envoy.filters.http.lua
  //       typed_config:
  //         "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
  //         stat_prefix: foo_script # This emits lua.foo_script.errors etc.
  //     - name: envoy.filters.http.lua
  //       typed_config:
  //         "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
  //         stat_prefix: bar_script # This emits lua.bar_script.errors etc.
  //
  string stat_prefix = 4;

  // If set to true, the Lua filter will clear the route cache automatically if the request
  // headers are modified by the Lua script. If set to false, the Lua filter will not clear the
  // route cache automatically.
  // Default is true for backward compatibility.
  google.protobuf.BoolValue clear_route_cache = 5;
}

message LuaPerRoute {
  oneof override {
    // Disable the Lua filter for this particular vhost or route. If disabled is specified in
    // multiple per-filter-configs, the most specific one will be used.
    bool disabled = 1 [(validate.rules).bool = {const: true}];

    // A name of a Lua source code stored in
    // :ref:`Lua.source_codes <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.source_codes>`.
    string name = 2 [(validate.rules).string = {min_len: 1}];

    // A configured per-route Lua source code that can be served by RDS or provided inline.
    config.core.v3.DataSource source_code = 3;
  }

  // Optional filter context for Lua script. This could be used to pass configuration
  // to Lua script. The Lua script can access the filter context using ``handle:filterContext()``.
  // For example:
  //
  // .. code-block:: lua
  //
  //   function envoy_on_request(request_handle)
  //     local filter_context = request_handle:filterContext()
  //     local filter_context_value = filter_context["key"]
  //     -- Do something with filter_context_value.
  //   end
  //
  google.protobuf.Struct filter_context = 4;
}
