gRPC Initial API Design

[KCarretto]

Summary

Our goal is to design an API for the beacon to interact with the teamserver, with the following required minimal features:

1. The beacon must be able to obtain new tasks to run
2. The beacon must be able to report the output of running those tasks

Design

edition = "2023";

package beacon;

option go_package = "github.com/kcarretto/tavern/internal/beacon/beaconpb";

import "google/protobuf/timestamp.proto";

/*
 * Messages
 */
 
 // Host information for the system a beacon is running on.
message Host {
    string identifier = 1;
    string name = 2;
    string primary_ip = 3;
}

// Agent information to identify the type of beacon.
message Agent {
    string identifier = 1;
}

// Beacon information that is unique to the current running beacon.
message Beacon {
    string identifier = 1;
    string principal = 2;
    Host host = 3;
    Agent agent = 4;
    uint64 interval = 5; // Duration until next callback, in seconds.
}

// Task instructions for the beacon to execute.
message Task {
    int32 id = 1;
    string eldritch = 2;
    map<string, string> parameters = 3;
}

// TaskError provides information when task execution fails.
message TaskError {
    string msg = 1;
}

// TaskOutput provides information about a running task.
message TaskOutput {
    int32 id = 1;
    string output = 2;
    TaskError error = 3;
    
    // Indicates the UTC timestamp task execution began, set only in the first message for reporting.
    google.protobuf.Timestamp exec_started_at = 4;

    // Indicates the UTC timestamp task execution completed, set only in last message for reporting.
    google.protobuf.Timestamp exec_finished_at = 5;
}

/*
 * RPC Messages
 */
message ClaimTasksRequest {
    Beacon beacon = 1;
}

message ClaimTasksResponse {
    repeated Task tasks = 1;
}

message ReportTaskOutputsRequest {
    repeated TaskOutput outputs = 1;
}

message ReportTaskOutputResponse {}

/*
 * Service
 */

service BeaconService {
    rpc ClaimTasks(ClaimTasksRequest) returns ClaimTasksResponse {}
    rpc ReportTaskOutputs(ReportTaskOutputsRequest) returns ReportTaskOutputsResponse {}
}

[hulto]

This makes sense to me 👌