// Copyright Envoy Gateway Authors
// SPDX-License-Identifier: Apache-2.0
// The full text of the Apache license is available in the LICENSE file at
// the root of the repo.

syntax = "proto3";

package envoygateway.extension;

import "envoy/config/cluster/v3/cluster.proto";
import "envoy/config/endpoint/v3/endpoint.proto";
import "envoy/config/listener/v3/listener.proto";
import "envoy/config/route/v3/route_components.proto";
import "envoy/config/route/v3/route.proto";
import "envoy/extensions/transport_sockets/tls/v3/secret.proto";

import "proto/extension/context.proto";

option go_package = "proto/extension";


service EnvoyGatewayExtension {
	// PostRouteModify provides a way for extensions to modify a route generated by Envoy Gateway before it is finalized.
	// Doing so allows extensions to configure/modify route fields configured by Envoy Gateway and also to configure the
	// Route's TypedPerFilterConfig which may be desirable to do things such as pass settings and information to
	// ext_authz filters.
	// PostRouteModify also passes a list of Unstructured data for the externalRefs owned by the extension on the HTTPRoute that
	// created this xDS route
	// PostRouteModify will only be executed if an extension is loaded and only on Routes which were generated from an HTTPRoute
	// that uses extension resources as externalRef filters.
    rpc PostRouteModify (PostRouteModifyRequest) returns (PostRouteModifyResponse) {};

	// PostVirtualHostModify provides a way for extensions to modify a VirtualHost generated by Envoy Gateway before it is finalized.
	// An extension can also make use of this hook to generate and insert entirely new Routes not generated by Envoy Gateway.
	// PostVirtualHostModify is always executed when an extension is loaded. An extension may return nil to not make any changes
    // to it.
    rpc PostVirtualHostModify(PostVirtualHostModifyRequest) returns (PostVirtualHostModifyResponse) {};

	// PostHTTPListenerModify allows an extension to make changes to a Listener generated by Envoy Gateway before it is finalized.
	// PostHTTPListenerModify is always executed when an extension is loaded. An extension may return nil
    // in order to not make any changes to it.
    rpc PostHTTPListenerModify(PostHTTPListenerModifyRequest) returns (PostHTTPListenerModifyResponse) {};

	// PostClusterModify provides a way for extensions to modify clusters generated by Envoy Gateway for custom backends.
	// This allows extensions to modify cluster configurations for custom backend types while letting Envoy Gateway
	// control cluster naming and basic configuration. This hook is called when custom backend resources are used
	// in HTTPRoute or GRPCRoute backendRefs.
	rpc PostClusterModify(PostClusterModifyRequest) returns (PostClusterModifyResponse) {};

	// PostEndpointsModify provides a way for extensions to modify a ClusterLoadAssignment generated by Envoy Gateway
	// before it is sent over EDS. This allows extensions to set per-endpoint metadata or apply endpoint overrides.
	rpc PostEndpointsModify(PostEndpointsModifyRequest) returns (PostEndpointsModifyResponse) {};

	// PostTranslateModify allows an extension to modify the translated xDS resources before they are sent to Envoy.
	// Extensions can inspect and update the generated clusters, secrets, listeners, and routes, or inject additional resources
	// that need to be created dynamically.
	// The lists returned by the extension are used as the final lists of clusters, secrets, listeners, and routes.
	// This hook is executed when an extension is loaded and has subscribed to the post-translation hook.
	rpc PostTranslateModify(PostTranslateModifyRequest) returns (PostTranslateModifyResponse) {};
}

// PostRouteModifyRequest sends a Route that was generated by Envoy Gateway along with context information to an extension so that the Route can be modified
message PostRouteModifyRequest {
    envoy.config.route.v3.Route route = 1;
    PostRouteExtensionContext post_route_context = 2;
}


// PostRouteModifyResponse is the expected response from an extension and contains a modified version of the Route that was sent
// If an extension returns a nil Route then it will not be modified
message PostRouteModifyResponse {
    envoy.config.route.v3.Route route = 1;
}


// PostClusterModifyRequest sends a single cluster to an extension for custom backend processing
message PostClusterModifyRequest {
    envoy.config.cluster.v3.Cluster cluster = 1;
    PostClusterExtensionContext post_cluster_context = 2;
}

// PostClusterModifyResponse is the expected response from an extension and contains a modified cluster
message PostClusterModifyResponse {
    envoy.config.cluster.v3.Cluster cluster = 1;
}

// PostEndpointsModifyRequest sends a ClusterLoadAssignment to an extension for endpoint modification
message PostEndpointsModifyRequest {
    envoy.config.endpoint.v3.ClusterLoadAssignment load_assignment = 1;
    PostEndpointsExtensionContext post_endpoints_context = 2;
}

// PostEndpointsModifyResponse is the expected response from an extension and contains a modified ClusterLoadAssignment
message PostEndpointsModifyResponse {
    envoy.config.endpoint.v3.ClusterLoadAssignment load_assignment = 1;
}


// PostVirtualHostModifyRequest sends a VirtualHost that was generated by Envoy Gateway along with context information to an extension so that the VirtualHost can be modified
message PostVirtualHostModifyRequest {
    envoy.config.route.v3.VirtualHost virtual_host = 1;
    PostVirtualHostExtensionContext post_virtual_host_context = 2;
}

// PostVirtualHostModifyResponse is the expected response from an extension and contains a modified version of the VirtualHost that was sent
// If an extension returns a nil Virtual Host then it will not be modified
message PostVirtualHostModifyResponse {
    envoy.config.route.v3.VirtualHost virtual_host = 1;
}

// PostVirtualHostModifyRequest sends a Listener that was generated by Envoy Gateway along with context information to an extension so that the Listener can be modified
message PostHTTPListenerModifyRequest {
    envoy.config.listener.v3.Listener listener = 1;
    PostHTTPListenerExtensionContext post_listener_context = 2;
}


// PostHTTPListenerModifyResponse is the expected response from an extension and contains a modified version of the Listener that was sent
// If an extension returns a nil Listener then it will not be modified
message PostHTTPListenerModifyResponse {
    envoy.config.listener.v3.Listener listener = 1;
}


// PostTranslateModifyRequest sends clusters, secrets, listeners, and routes to an extension.
// The extension is free to add/modify/remove the resources it received.
message PostTranslateModifyRequest {
    PostTranslateExtensionContext post_translate_context = 1;
    repeated envoy.config.cluster.v3.Cluster clusters = 2;
    repeated envoy.extensions.transport_sockets.tls.v3.Secret secrets = 3;
    repeated envoy.config.listener.v3.Listener listeners = 4;
    repeated envoy.config.route.v3.RouteConfiguration routes = 5;
}


// PostTranslateModifyResponse is the expected response from an extension and contains
// the full list of xDS clusters, secrets, listeners, and routes to be used for the xDS config.
message PostTranslateModifyResponse {
    repeated envoy.config.cluster.v3.Cluster clusters = 1;
    repeated envoy.extensions.transport_sockets.tls.v3.Secret secrets = 2;
    repeated envoy.config.listener.v3.Listener listeners = 3;
    repeated envoy.config.route.v3.RouteConfiguration routes = 4;
}