// Copyright 2018 Istio 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";

// $title: Mixer Adapter Model
// $overview: Definitions used to create adapters and templates
// $location: https://istio.io/docs/reference/api/mixer/istio.mixer.adapter.model.v1beta1.html

// This package defines the service and types used by adapter code to serve requests from Mixer.
// This package also defines the types that are used to create Mixer templates.
package istio.mixer.adapter.model.v1beta1;

option go_package="istio.io/api/mixer/adapter/model/v1beta1";
option cc_generic_services = true;

import "google/protobuf/any.proto";
import "google/rpc/status.proto";

// `InfrastructureBackend` is implemented by backends that wants to provide telemetry and policy functionality to Mixer as an
// out of process adapter.
//
// `InfrastructureBackend` allows Mixer and the backends to have a session based model. In a session based model, Mixer passes
// the relevant configuration state to the backend only once and estabilshes a session using a session identifier.
// All future communications between Mixer and the backend uses the session identifier which refers to the previously
// passed in configuration data.
//
// For a given `InfrastructureBackend`, Mixer calls the `Validate` function, followed by `CreateSession`. The `session_id`
// returned from `CreateSession` is used to make subsequent request-time Handle calls and the eventual `CloseSession` function.
// Mixer assumes that, given the `session_id`, the backend can retrieve the necessary context to serve the
// Handle calls that contains the request-time payload (template-specific instance protobuf).
service InfrastructureBackend {
    // Validates the handler configuration along with the template-specific instances that would be routed to that
    // handler. The `CreateSession` for a specific handler configuration is invoked only if its associated `Validate`
    // call has returned success.
    rpc  Validate(ValidateRequest) returns (ValidateResponse);

    // Creates a session for a given handler configuration and the template-specific instances that would be routed to
    // that handler. For every handler configuration, Mixer creates a separate session by invoking `CreateSession`
    // on the backend.
    //
    // `CreateSessionRequest` contains the adapter specific handler configuration and the inferred type information about
    // the instances the handler would receive during request processing.
    //
    // `CreateSession` must return a `session_id` which Mixer uses to invoke template-specific Handle functions during
    // request processing. The `session_id` provides the Handle functions a way to retrieve the necessary configuration
    // associated with the session. Upon Mixer configuration change, Mixer will re-invoke `CreateSession` for all
    // handler configurations whose existing sessions are invalidated or didn't existed.
    //
    // Backend is allowed to return the same session id if given the same configuration block.
    // This would happen when multiple instances of Mixer in a deployment all create sessions with the same configuration.
    // Note that given individial instances of Mixer can call `CloseSession`, reusing `session_id` by the backend
    // assumes that the backend is doing reference counting.
    //
    // If the backend couldn't create a session for a specific handler configuration and
    // returns non S_OK status, Mixer will not make request-time Handle calls associated with that handler configuration.
    rpc  CreateSession(CreateSessionRequest) returns (CreateSessionResponse);

    // Closes the session associated with the `session_id`. Mixer closes a session when its associated handler
    // configuration or the instance configuration changes. Backend is supposed to cleanup all the resources associated
    // with the session_id referenced by CloseSessionRequest.
    rpc  CloseSession(CloseSessionRequest) returns (CloseSessionResponse);
}

// Request message for `CreateSession` method.
message CreateSessionRequest {
    // Adapter specific configuration.
    google.protobuf.Any adapter_config = 1;
    // Map of instance names to their template-specific inferred type.
    map<string, google.protobuf.Any> inferred_types = 2;
}

// Response message for `CreateSession` method.
message CreateSessionResponse {
    // Id of the created session.
    string session_id = 1;
    // The success/failure status of create session call.
    google.rpc.Status status = 2;
}

// Request message for `Validate` method.
message ValidateRequest {
    // Adapter specific configuration.
    google.protobuf.Any adapter_config = 1;
    // Map of instance names to their template-specific inferred type.
    map<string, google.protobuf.Any> inferred_types = 2;
}

// Response message for `Validate` method.
message ValidateResponse {
    // The success/failure status of validation call.
    google.rpc.Status status = 1;
}

// Request message for `CloseSession` method.
message CloseSessionRequest {
    // Id of the session to be closed.
    string session_id = 1;
}

// Response message for `CloseSession` method.
message CloseSessionResponse {
    // The success/failure status of close session call.
    google.rpc.Status status = 1;
}
