/*
 * Copyright 2018 The Feast 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
 *
 *     https://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 feast.serving;

import "google/protobuf/timestamp.proto";
import "feast/types/Value.proto";
import "tensorflow_metadata/proto/v0/statistics.proto";

option java_package = "feast.proto.serving";
option java_outer_classname = "ServingAPIProto";
option go_package = "github.com/feast-dev/feast/sdk/go/protos/feast/serving";

service ServingService {
    // Get information about this Feast serving.
    rpc GetFeastServingInfo (GetFeastServingInfoRequest) returns (GetFeastServingInfoResponse);

    // Get online features (v2) synchronously.
    rpc GetOnlineFeaturesV2 (GetOnlineFeaturesRequestV2) returns (GetOnlineFeaturesResponse);
}

message GetFeastServingInfoRequest {}

message GetFeastServingInfoResponse {
    // Feast version of this serving deployment.
    string version = 1;

    // Type of serving deployment, either ONLINE or BATCH. Different store types support different
    // feature retrieval methods.
    FeastServingType type = 2;

    // Note: Batch specific options start from 10.
    // Staging location for this serving store, if any.
    string job_staging_location = 10;
}

message FeatureReferenceV2 {
    // Name of the Feature Table to retrieve the feature from.
    string feature_table = 1;

    // Name of the Feature to retrieve the feature from.
    string name = 2;
}

message GetOnlineFeaturesRequestV2 {
    // List of features that are being retrieved
    repeated FeatureReferenceV2 features = 4;

    // List of entity rows, containing entity id and timestamp data.
    // Used during retrieval of feature rows and for joining feature
    // rows into a final dataset
    repeated EntityRow entity_rows = 2;

    // Optional field to specify project name override. If specified, uses the
    // given project for retrieval. Overrides the projects specified in
    // Feature References if both are specified.
    string project = 5;

    message EntityRow {
        // Request timestamp of this row. This value will be used,
        // together with maxAge, to determine feature staleness.
        google.protobuf.Timestamp timestamp = 1;

        // Map containing mapping of entity name to entity value.
        map<string,feast.types.Value> fields = 2;
    }
}

message GetOnlineFeaturesResponse {
    // Feature values retrieved from feast.
    repeated FieldValues field_values = 1;

    message FieldValues {
        // Map of feature or entity name to feature/entity values.
        // Timestamps are not returned in this response.
        map<string, feast.types.Value> fields = 1;
        // Map of feature or entity name to feature/entity statuses/metadata.
        map<string, FieldStatus> statuses = 2;
    }
   
    enum FieldStatus {
        // Status is unset for this field.
        INVALID = 0;

        // Field value is present for this field and age is within max age.
        PRESENT = 1;

        // Values could be found for entity key and age is within max age, but
        // this field value is assigned a value on ingestion into feast.
        NULL_VALUE = 2;

        // Entity key did not return any values as they do not exist in Feast.
        // This could suggest that the feature values have not yet been ingested
        // into feast or the ingestion failed.
        NOT_FOUND = 3;

        // Values could be found for entity key, but field values are outside the maximum 
        // allowable range.
        OUTSIDE_MAX_AGE = 4;
    }
}

enum FeastServingType {
    FEAST_SERVING_TYPE_INVALID = 0;
    // Online serving receives entity data directly and synchronously and will
    // respond immediately.
    FEAST_SERVING_TYPE_ONLINE = 1;
    // Batch serving receives entity data asynchronously and orchestrates the
    // retrieval through a staging location.
    FEAST_SERVING_TYPE_BATCH = 2;
}
