122 lines
4.3 KiB
Protocol Buffer
122 lines
4.3 KiB
Protocol Buffer
syntax = "proto3";
|
|
package nxmesh.agent.v1;
|
|
|
|
option go_package = "github.com/nxmesh/api/agent/v1";
|
|
|
|
// For all file paths in this proto, we use forward slashes ("/") as the separator, even on Windows. This is because gRPC and protobuf are designed to be cross-platform and forward slashes are universally accepted as path separators in URLs and many programming languages. Using forward slashes ensures consistency and avoids issues with escaping backslashes on different platforms.
|
|
// All file paths MUST be relative paths from other config files, e.g. "site.conf", "private/example.com.conf". Absolute paths or path traversal above the config directory should be rejected by the agent for security reasons. The config files must live within the generated config directory, e.g. "/etc/nginx/conf-<timestamp>/site.conf". This allows the agent to manage the lifecycle of config files, e.g. cleanup old configs after successful apply.
|
|
|
|
// AgentService defines the bidirectional communication between master and agents
|
|
service AgentService {
|
|
// Stream establishes a persistent connection for real-time communication
|
|
rpc Stream(stream AgentMessage) returns (stream MasterMessage);
|
|
|
|
rpc ConnectionTest(TestRequest) returns (TestResponse);
|
|
}
|
|
|
|
message TestRequest {
|
|
// no fields needed for test request
|
|
}
|
|
|
|
message TestResponse {
|
|
bool success = 1;
|
|
string error_message = 2; // if success is false, this field should contain the error message
|
|
}
|
|
|
|
// Messages sent from master to agent
|
|
message MasterMessage {
|
|
int64 timestamp = 1;
|
|
string message_id = 2;
|
|
oneof payload {
|
|
// requests
|
|
ConfigUpdate config_update = 3;
|
|
Command command = 4;
|
|
}
|
|
}
|
|
|
|
// Messages sent from agent to master
|
|
message AgentMessage {
|
|
string agent_id = 1;
|
|
int64 timestamp = 2;
|
|
string message_id = 3;
|
|
oneof payload {
|
|
// responses
|
|
ConfigUpdateResult config_update_result = 6;
|
|
CommandResult command_result = 7;
|
|
}
|
|
}
|
|
|
|
//
|
|
//
|
|
//
|
|
|
|
// ConfigUpdate represents a request from master to agent to update the configuration
|
|
message ConfigUpdate {
|
|
string config_id = 1; // unique identifier for this config update
|
|
string version = 2;
|
|
// The root config is the main nginx.conf file, this file will be used as the entry point for nginx configuration. The content of this file should include references to other config files if needed. The agent will write this root config to the nginx config directory and use it to reload nginx.
|
|
ConfigContent root_config = 3;
|
|
// The other config files that are referenced by the root config, e.g. "site.conf", "private/example.com.conf". If the root config does not reference any other config files, this field can be left empty. The agent will write these config files to the nginx config directory and ensure they are included in the root config.
|
|
repeated ConfigContent configs = 4;
|
|
}
|
|
|
|
message ConfigContent {
|
|
// relative path from other config files, e.g. "site.conf", "private/example.com.conf"
|
|
string path = 1;
|
|
string content = 2;
|
|
}
|
|
|
|
message ConfigUpdateResult {
|
|
string config_id = 1; // should match the config_id in ConfigUpdate
|
|
string version = 2;
|
|
bool success = 3;
|
|
optional ConfigUpdateError error_message = 4; // if success is false, this field should contain the error message
|
|
}
|
|
|
|
enum ConfigUpdateError {
|
|
UNKNOWN = 0;
|
|
INVALID_CONFIG = 1; // the config content is invalid, e.g. syntax error
|
|
WRITE_FAILED = 2; // failed to write the config file to disk
|
|
RELOAD_FAILED = 3; // failed to reload nginx with the new config
|
|
}
|
|
|
|
//
|
|
//
|
|
//
|
|
|
|
// TODO: allow setting the default fallback and the corresponding default nginx root config when nginx reload fails to re-use old config, "use default config", "stop nginx".
|
|
|
|
// Command represents a request from master to agent to execute a command, e.g. "reload", "test"
|
|
message Command {
|
|
oneof command {
|
|
ReloadCommand reload = 1;
|
|
TestCommand test = 2;
|
|
}
|
|
}
|
|
|
|
message ReloadCommand {
|
|
// no additional fields needed for reload command
|
|
}
|
|
|
|
message TestCommand {
|
|
// no additional fields needed for test command
|
|
}
|
|
|
|
message CommandResult {
|
|
oneof result {
|
|
ReloadResult reload_result = 1;
|
|
TestResult test_result = 2;
|
|
}
|
|
}
|
|
|
|
message ReloadResult {
|
|
bool success = 1;
|
|
string error_message = 2; // if success is false, this field should contain the error message
|
|
}
|
|
|
|
message TestResult {
|
|
bool success = 1;
|
|
string error_message = 2; // if success is false, this field should contain the error message
|
|
}
|
|
|