github.com/mutagen-io/mutagen@v0.18.0-rc1/pkg/synchronization/endpoint/remote/protocol.proto

syntax = "proto3";

package remote;

option go_package = "github.com/mutagen-io/mutagen/pkg/synchronization/endpoint/remote";

import "synchronization/rsync/engine.proto";
import "synchronization/configuration.proto";
import "synchronization/version.proto";
import "synchronization/core/archive.proto";
import "synchronization/core/change.proto";
import "synchronization/core/problem.proto";

// InitializeSynchronizationRequest encodes a request for endpoint
// initialization.
message InitializeSynchronizationRequest {
    // Session is the session identifier.
    string session = 1;
    // Version is the session version.
    synchronization.Version version = 2;
    // Configuration is the session configuration.
    synchronization.Configuration configuration = 3;
    // Root is the synchronization root path.
    string root = 4;
    // Alpha indicates whether or not the endpoint should behave as alpha (as
    // opposed to beta).
    bool alpha = 5;
}

// InitializeSynchronizationResponse encodes initialization results.
message InitializeSynchronizationResponse {
    // Error is the error message (if any) resulting from initialization.
    string error = 1;
}

// PollRequest encodes a request for one-shot polling.
message PollRequest {}

// PollCompletionRequest is paired with PollRequest and indicates a request for
// early polling completion or an acknowledgement of completion.
message PollCompletionRequest{}

// PollResponse indicates polling completion.
message PollResponse {
    // Error is the error message (if any) resulting from polling.
    string error = 1;
}

// ScanRequest encodes a request for a scan.
message ScanRequest {
    // BaselineSnapshotSignature is the rsync signature to use as the base for
    // differentially transmitting snapshots.
    rsync.Signature baselineSnapshotSignature = 1;
    // Full indicates whether or not to force a full (warm) scan, temporarily
    // avoiding any acceleration that might be available on the endpoint.
    bool full = 2;
}

// ScanCompletionRequest is paired with a ScanRequest and indicates a request
// for scan cancellation or an acknowledgement of completion.
message ScanCompletionRequest{}

// ScanResponse encodes the results of a scan.
message ScanResponse {
    // SnapshotDelta are the operations need to reconstruct the snapshot against
    // the specified base.
    repeated rsync.Operation snapshotDelta = 1;
    // Error is the error message (if any) resulting from scanning.
    string error = 2;
    // TryAgain indicates whether or not the error is ephermeral.
    bool tryAgain = 3;
}

// StageRequest encodes a request for staging.
message StageRequest {
    // Paths lists the paths that need to be staged.
    repeated string paths = 1;
    // Digests lists the digests for the paths that need to be staged. Its
    // length and contents correspond to that of Paths.
    repeated bytes digests = 2;
}

// StageResponse encodes the results of staging initialization.
message StageResponse {
    // Paths are the paths that need to be staged after filtering. If its length
    // is zero and the length of Signatures is non-zero, then it's assumed that
    // all paths are required and (in that scenario) the length of Signatures
    // must be equal to the length of the original path list.
    repeated string paths = 1;
    // Signatures are the rsync signatures of the paths needing to be staged.
    repeated rsync.Signature signatures = 2;
    // Error is the error message (if any) resulting from staging
    // initialization.
    string error = 3;
}

// SupplyRequest indicates a request for supplying files.
message SupplyRequest {
    // Paths are the paths to provide (relative to the synchronization root).
    repeated string paths = 1;
    // Signatures are the rsync signatures of the paths needing to be staged.
    repeated rsync.Signature signatures = 2;
}

// TransitionRequest encodes a request for transition application.
message TransitionRequest {
    // Transitions are the transitions that need to be applied.
    repeated core.Change transitions = 1;
}

// TransitionCompletionRequest is paired with a TransitionRequest and indicates
// a request for transition cancellation or an acknowledgement of completion.
message TransitionCompletionRequest{}

// TransitionResponse encodes the results of transitioning.
message TransitionResponse {
    // Results are the resulting contents post-transition.
    // HACK: We have to use Archive to wrap our Entry results here because
    // Protocol Buffers won't encode a nil pointer in a repeated element in
    // certain cases, and the results of transitions may very well be nil. gob
    // also exhibits this problem.
    repeated core.Archive results = 1;
    // Problems are any problems encountered during the transition operation.
    repeated core.Problem problems = 2;
    // StagerMissingFiles indicates whether or not the endpoint's stager
    // indicated missing files during transitioning.
    bool stagerMissingFiles = 3;
    // Error is the error message (if any) resulting from the remote transition
    // method. This will always be an empty string since transition doesn't
    // return errors from local endpoints, but to match the endpoint interface
    // (which allows for transition errors due to network failures with remote
    // endpoints), we include this field.
    // TODO: Should we just remove this field? Doing so would rely on knowledge
    // of localEndpoint's transition behavior.
    string error = 4;
}

// EndpointRequest is a sum type that can transmit any type of endpoint request.
// Only the sent request will be non-nil. We intentionally avoid using Protocol
// Buffers' oneof feature because it generates really ugly code and an unwieldy
// API, at least in Go. Manually checking for exclusivity is not difficult.
message EndpointRequest {
    // Poll represents a poll request.
    PollRequest poll = 1;
    // Scan represents a scan request.
    ScanRequest scan = 2;
    // Stage represents a stage request.
    StageRequest stage = 3;
    // Supply represents a supply request.
    SupplyRequest supply = 4;
    // Transition represents a transition request.
    TransitionRequest transition = 5;
}