val.proto

/********************************************************************************
 * Copyright (c) 2022 Contributors to the Eclipse Foundation
 *
 * See the NOTICE file(s) distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Apache License 2.0 which is available at
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * SPDX-License-Identifier: Apache-2.0
 ********************************************************************************/

syntax = "proto3";

package kuksa.val.v1;

option go_package = "kuksa/val/v1";

import "kuksa/val/v1/types.proto";

// Note on authorization:
// Tokens (auth-token or auth-uuid) are sent as (GRPC / http2) metadata.
//
// The auth-token is a JWT compliant token as the examples found here:
// https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/certificates/jwt
//
// See also https://github.com/eclipse-kuksa/kuksa-databroker/blob/main/doc/authorization.md#jwt-access-token
//
// Upon reception of auth-token, server shall generate an auth-uuid in metadata
// that the client can use instead of auth-token in subsequent calls.

service VAL {
  // Get entries
  rpc Get(GetRequest) returns (GetResponse);

  // Set entries
  rpc Set(SetRequest) returns (SetResponse);

  rpc StreamedUpdate(stream StreamedUpdateRequest) returns (stream StreamedUpdateResponse);

  // Subscribe to a set of entries
  //
  // Returns a stream of notifications.
  //
  // InvalidArgument is returned if the request is malformed.
  rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse);

  // Shall return information that allows the client to determine
  // what server/server implementation/version it is talking to
  // eg. kuksa-databroker 0.5.1
  rpc GetServerInfo(GetServerInfoRequest) returns (GetServerInfoResponse);
}

// Define which data we want
message EntryRequest {
  string path           = 1;
  View view             = 2;
  repeated Field fields = 3;
}

// Request a set of entries.
message GetRequest {
  repeated EntryRequest entries = 1;
}

// Global errors are specified in `error`.
// Errors for individual entries are specified in `errors`.
message GetResponse {
  repeated DataEntry entries     = 1;
  repeated DataEntryError errors = 2;
  Error error                    = 3;
}

// Define the data we want to set
message EntryUpdate {
  DataEntry entry       = 1;
  repeated Field fields = 2;
}

// A list of entries to be updated
message SetRequest {
  repeated EntryUpdate updates = 1;
}

// Global errors are specified in `error`.
// Errors for individual entries are specified in `errors`.
message SetResponse {
  Error error                    = 1;
  repeated DataEntryError errors = 2;
}

message StreamedUpdateRequest {
  repeated EntryUpdate updates = 1;
}

message StreamedUpdateResponse {
  Error error                    = 1;
  repeated DataEntryError errors = 2;
}

// Define what to subscribe to
message SubscribeEntry {
  string path           = 1;
  View view             = 2;
  repeated Field fields = 3;
}

// Subscribe to changes in datapoints.
message SubscribeRequest {
  repeated SubscribeEntry entries = 1;
}

// A subscription response
message SubscribeResponse {
  repeated EntryUpdate updates = 1;
}

message GetServerInfoRequest {
  // Nothing yet
}

message GetServerInfoResponse {
  string name    = 1;
  string version = 2;
}