package synchronization

Get desktop application:
View/edit binary Protocol Buffers messages

Synchronization manages the lifecycle of synchronization sessions.

• rpc Create (CreateRequest, CreateResponse)

  synchronization.proto:128

  Create creates a new session.

  message CreateRequest

  synchronization.proto:38

  CreateRequest encodes a request for session creation.

  • string prompter = 1

    Prompter is the prompter identifier to use for creating sessions.

  • optional CreationSpecification specification = 2

    Specification is the creation specification.

  message CreateResponse

  synchronization.proto:46

  CreateResponse encodes a session creation response.

  • string session = 1

    Session is the resulting session identifier.

• rpc List (ListRequest, ListResponse)

  synchronization.proto:130

  List returns metadata for existing sessions.

  message ListRequest

  synchronization.proto:52

  ListRequest encodes a request for session metadata.

  • optional selection.Selection selection = 1

    Selection is the session selection criteria.

  • uint64 previousStateIndex = 2

    PreviousStateIndex is the previously seen state index. 0 may be provided to force an immediate state listing.

  message ListResponse

  synchronization.proto:61

  ListResponse encodes session metadata.

  • uint64 stateIndex = 1

    StateIndex is the state index associated with the session metadata.

  • repeated State sessionStates = 2

    SessionStates are the session metadata states.

• rpc Flush (FlushRequest, FlushResponse)

  synchronization.proto:132

  Flush flushes sessions.

  message FlushRequest

  synchronization.proto:69

  FlushRequest encodes a request to flush sessions.

  • string prompter = 1

    Prompter is the prompter to use for status message updates.

  • optional selection.Selection selection = 2

    Selection is the session selection criteria.

  • bool skipWait = 3

    SkipWait indicates whether or not the operation should avoid blocking.

  message FlushResponse

  synchronization.proto:79

  FlushResponse indicates completion of flush operation(s).

  (message has no fields)

• rpc Pause (PauseRequest, PauseResponse)

  synchronization.proto:134

  Pause pauses sessions.

  message PauseRequest

  synchronization.proto:82

  PauseRequest encodes a request to pause sessions.

  • string prompter = 1

    Prompter is the prompter to use for status message updates.

  • optional selection.Selection selection = 2

    Selection is the session selection criteria.

  message PauseResponse

  synchronization.proto:90

  PauseResponse indicates completion of pause operation(s).

  (message has no fields)

• rpc Resume (ResumeRequest, ResumeResponse)

  synchronization.proto:136

  Resume resumes paused or disconnected sessions.

  message ResumeRequest

  synchronization.proto:93

  ResumeRequest encodes a request to resume sessions.

  • string prompter = 1

    Prompter is the prompter identifier to use for resuming sessions.

  • optional selection.Selection selection = 2

    Selection is the session selection criteria.

  message ResumeResponse

  synchronization.proto:101

  ResumeResponse indicates completion of resume operation(s).

  (message has no fields)

• rpc Reset (ResetRequest, ResetResponse)

  synchronization.proto:138

  Reset resets sessions' histories.

  message ResetRequest

  synchronization.proto:104

  ResetRequest encodes a request to reset sessions.

  • string prompter = 1

    Prompter is the prompter identifier to use for resetting sessions.

  • optional selection.Selection selection = 2

    Selection is the session selection criteria.

  message ResetResponse

  synchronization.proto:112

  ResetResponse indicates completion of reset operation(s).

  (message has no fields)

• rpc Terminate (TerminateRequest, TerminateResponse)

  synchronization.proto:140

  Terminate terminates sessions.

  message TerminateRequest

  synchronization.proto:115

  TerminateRequest encodes a request to terminate sessions.

  • string prompter = 1

    Prompter is the prompter to use for status message updates.

  • optional selection.Selection selection = 2

    Selection is the session selection criteria.

  message TerminateResponse

  synchronization.proto:123

  TerminateResponse indicates completion of termination operation(s).

  (message has no fields)

Configuration encodes session configuration parameters. It is used for create commands to specify configuration options, for loading global configuration options, and for storing a merged configuration inside sessions. It should be considered immutable.

Synchronization parameters (fields 11-20). NOTE: These run from field indices 11-20 (rather than 1-10, which are reserved for symbolic link configuration parameters) due to the historical order in which these fields were added. Field 17 (the digest algorithm) is also listed out of its chronological order of addition due to its relative importance in the configuration.

Used in: remote.InitializeSynchronizationRequest, CreationSpecification, Session

• core.SynchronizationMode synchronizationMode = 11

  SynchronizationMode specifies the synchronization mode that should be used in synchronization.

• hashing.Algorithm hashingAlgorithm = 17

  HashingAlgorithm specifies the content hashing algorithm used to track content and perform differential transfers.

• uint64 maximumEntryCount = 12

  MaximumEntryCount specifies the maximum number of filesystem entries that endpoints will tolerate managing. A zero value indicates no limit.

• uint64 maximumStagingFileSize = 13

  MaximumStagingFileSize is the maximum (individual) file size that endpoints will stage. A zero value indicates no limit.

• behavior.ProbeMode probeMode = 14

  ProbeMode specifies the filesystem probing mode.

• ScanMode scanMode = 15

  ScanMode specifies the synchronization root scanning mode.

• StageMode stageMode = 16

  StageMode specifies the file staging mode.

• core.SymbolicLinkMode symbolicLinkMode = 1

  SymbolicLinkMode specifies the symbolic link mode.

• WatchMode watchMode = 21

  WatchMode specifies the filesystem watching mode.

• uint32 watchPollingInterval = 22

  WatchPollingInterval specifies the interval (in seconds) for poll-based file monitoring. A value of 0 specifies that the default interval should be used.

• ignore.Syntax ignoreSyntax = 34

  IgnoreSyntax specifies the syntax and semantics to use for ignores. NOTE: This field is out of order due to the historical order in which it was added.

• repeated string defaultIgnores = 31

  DefaultIgnores specifies the ignore patterns brought in from the global configuration. DEPRECATED: This field is no longer used when loading from global configuration. Instead, ignores provided by global configuration are simply merged into the ignore list of the main configuration. However, older sessions still use this field.

• repeated string ignores = 32

  Ignores specifies the ignore patterns brought in from the create request.

• ignore.IgnoreVCSMode ignoreVCSMode = 33

  IgnoreVCSMode specifies the VCS ignore mode that should be used in synchronization.

• core.PermissionsMode permissionsMode = 61

  PermissionsMode species the manner in which permissions should be propagated between endpoints.

• uint32 defaultFileMode = 63

  DefaultFileMode specifies the default permission mode to use for new files in "portable" permission propagation mode.

• uint32 defaultDirectoryMode = 64

  DefaultDirectoryMode specifies the default permission mode to use for new files in "portable" permission propagation mode.

• string defaultOwner = 65

  DefaultOwner specifies the default owner identifier to use when setting ownership of new files and directories in "portable" permission propagation mode.

• string defaultGroup = 66

  DefaultGroup specifies the default group identifier to use when setting ownership of new files and directories in "portable" permission propagation mode.

• compression.Algorithm compressionAlgorithm = 81

  CompressionAlgorithm specifies the compression algorithm to use when communicating with the endpoint. This only applies to remote endpoints.

CreationSpecification contains the metadata required for a new session.

Used in: CreateRequest

• optional url.URL alpha = 1

  Alpha is the alpha endpoint URL for the session.

• optional url.URL beta = 2

  Beta is the beta endpoint URL for the session.

• optional Configuration configuration = 3

  Configuration is the base session configuration. It is the result of merging the global configuration (unless disabled), any manually specified configuration file, and any command line configuration parameters.

• optional Configuration configurationAlpha = 4

  ConfigurationAlpha is the alpha-specific session configuration. It is determined based on command line configuration parameters.

• optional Configuration configurationBeta = 5

  ConfigurationBeta is the beta-specific session configuration. It is determined based on command line configuration parameters.

• string name = 6

  Name is the name for the session object.

• map<string, string> labels = 7

  Labels are the labels for the session object.

• bool paused = 8

  Paused indicates whether or not to create the session pre-paused.

EndpointState encodes the current state of a synchronization endpoint. It is mutable within the context of the daemon, so it should be accessed and modified in a synchronized fashion. Outside of the daemon (e.g. when returned via the API), it should be considered immutable.

Used in: State

• bool connected = 1

  Connected indicates whether or not the controller is currently connected to the endpoint.

• bool scanned = 2

  Scanned indicates whether or not at least one scan has been performed on the endpoint.

• uint64 directories = 3

  Directories is the number of synchronizable directory entries contained in the last snapshot from the endpoint.

• uint64 files = 4

  Files is the number of synchronizable file entries contained in the last snapshot from the endpoint.

• uint64 symbolicLinks = 5

  SymbolicLinks is the number of synchronizable symbolic link entries contained in the last snapshot from the endpoint.

• uint64 totalFileSize = 6

  TotalFileSize is the total size of all synchronizable files referenced by the last snapshot from the endpoint.

• repeated core.Problem scanProblems = 7

  ScanProblems is the list of non-terminal problems encountered during the last scanning operation on the endpoint. This list may be a truncated version of the full list if too many problems are encountered to report via the API, in which case ExcludedScanProblems will be non-zero.

• uint64 excludedScanProblems = 8

  ExcludedScanProblems is the number of problems that have been excluded from ScanProblems due to truncation. This value can be non-zero only if ScanProblems is non-empty.

• repeated core.Problem transitionProblems = 9

  TransitionProblems is the list of non-terminal problems encountered during the last transition operation on the endpoint. This list may be a truncated version of the full list if too many problems are encountered to report via the API, in which case ExcludedTransitionProblems will be non-zero.

• uint64 excludedTransitionProblems = 10

  ExcludedTransitionProblems is the number of problems that have been excluded from TransitionProblems due to truncation. This value can be non-zero only if TransitionProblems is non-empty.

• optional rsync.ReceiverState stagingProgress = 11

  StagingProgress is the rsync staging progress. It is non-nil if and only if the endpoint is currently staging files.

ScanMode specifies the mode for synchronization root scanning.

Used in: Configuration

• ScanModeDefault = 0

  ScanMode_ScanModeDefault represents an unspecified scan mode. It should be converted to one of the following values based on the desired default behavior.

• ScanModeFull = 1

  ScanMode_ScanModeFull specifies that full scans should be performed on each synchronization cycle.

• ScanModeAccelerated = 2

  ScanMode_ScanModeAccelerated specifies that scans should attempt to use watch-based acceleration.

Session represents a synchronization session configuration and persistent state. It is mutable within the context of the daemon, so it should be accessed and modified in a synchronized fashion. Outside of the daemon (e.g. when returned via the API), it should be considered immutable.

The identifier, version, creationTime, and creatingVersion* fields are considered the "header" fields for all session versions. A message composed purely of these fields is guaranteed to be compatible with all future session versions. This can be used to dispatch session decoding to more specific message structures once multiple session version formats are implemented.

Used in: State

• string identifier = 1

  Identifier is the (unique) session identifier. It is static. It cannot be empty.

• Version version = 2

  Version is the session version. It is static.

• optional google.protobuf.Timestamp creationTime = 3

  CreationTime is the creation time of the session. It is static. It cannot be nil.

• uint32 creatingVersionMajor = 4

  CreatingVersionMajor is the major version component of the version of Mutagen which created the session. It is static.

• uint32 creatingVersionMinor = 5

  CreatingVersionMinor is the minor version component of the version of Mutagen which created the session. It is static.

• uint32 creatingVersionPatch = 6

  CreatingVersionPatch is the patch version component of the version of Mutagen which created the session. It is static.

• optional url.URL alpha = 7

  Alpha is the alpha endpoint URL. It is static. It cannot be nil.

• optional url.URL beta = 8

  Beta is the beta endpoint URL. It is static. It cannot be nil.

• optional Configuration configuration = 9

  Configuration is the flattened session configuration. It is static. It cannot be nil.

• optional Configuration configurationAlpha = 11

  ConfigurationAlpha are the alpha-specific session configuration overrides. It is static. It may be nil for existing sessions loaded from disk, but it is not considered valid unless non-nil, so it should be replaced with an empty default value in-memory if a nil on-disk value is detected.

• optional Configuration configurationBeta = 12

  ConfigurationBeta are the beta-specific session configuration overrides. It is static. It may be nil for existing sessions loaded from disk, but it is not considered valid unless non-nil, so it should be replaced with an empty default value in-memory if a nil on-disk value is detected.

• string name = 14

  Name is a user-friendly name for the session. It may be empty and is not guaranteed to be unique across all sessions. It is only used as a simpler handle for specifying sessions. It is static.

• map<string, string> labels = 13

  Labels are the session labels. They are static.

• bool paused = 10

  Paused indicates whether or not the session is marked as paused.

  NOTE: Fields 11, 12, 13, and 14 are used above. They are out of order for historical reasons.

StageMode specifies the mode for file staging.

Used in: Configuration

• StageModeDefault = 0

  StageMode_StageModeDefault represents an unspecified staging mode. It should be converted to one of the following values based on the desired default behavior.

• StageModeMutagen = 1

  StageMode_StageModeMutagen specifies that files should be staged in the Mutagen data directory.

• StageModeNeighboring = 2

  StageMode_StageModeNeighboring specifies that files should be staged in a directory which neighbors the synchronization root.

• StageModeInternal = 3

  StageMode_StageModeInternal specified that files should be staged in a directory contained within a synchronization root. This mode will only function if the synchronization root already exists.

State encodes the current state of a synchronization session. It is mutable within the context of the daemon, so it should be accessed and modified in a synchronized fashion. Outside of the daemon (e.g. when returned via the API), it should be considered immutable.

Used in: ListResponse

• optional Session session = 1

  Session is the session metadata. If the session is paused, then the remainder of the fields in this structure should be ignored.

• Status status = 2

  Status is the session status.

• string lastError = 3

  LastError is the last error to occur during synchronization. It is cleared after a successful synchronization cycle.

• uint64 successfulCycles = 4

  SuccessfulCycles is the number of successful synchronization cycles to occur since successfully connecting to the endpoints.

• repeated core.Conflict conflicts = 5

  Conflicts are the content conflicts identified during reconciliation. This list may be a truncated version of the full list if too many conflicts are encountered to report via the API, in which case ExcludedConflicts will be non-zero.

• uint64 excludedConflicts = 6

  ExcludedConflicts is the number of conflicts that have been excluded from Conflicts due to truncation. This value can be non-zero only if conflicts is non-empty.

• optional EndpointState alphaState = 7

  AlphaState encodes the state of the alpha endpoint. It is always non-nil.

• optional EndpointState betaState = 8

  BetaState encodes the state of the beta endpoint. It is always non-nil.

Status encodes the status of a synchronization session.

Used in: State

• Disconnected = 0

  Status_Disconnected indicates that the session is unpaused but not currently connected or connecting to either endpoint.

• HaltedOnRootEmptied = 1

  Status_HaltedOnRootEmptied indicates that the session is halted due to the root emptying safety check.

• HaltedOnRootDeletion = 2

  Status_HaltedOnRootDeletion indicates that the session is halted due to the root deletion safety check.

• HaltedOnRootTypeChange = 3

  Status_HaltedOnRootTypeChange indicates that the session is halted due to the root type change safety check.

• ConnectingAlpha = 4

  Status_ConnectingAlpha indicates that the session is attempting to connect to the alpha endpoint.

• ConnectingBeta = 5

  Status_ConnectingBeta indicates that the session is attempting to connect to the beta endpoint.

• Watching = 6

  Status_Watching indicates that the session is watching for filesystem changes.

• Scanning = 7

  Status_Scanning indicates that the session is scanning the filesystem on each endpoint.

• WaitingForRescan = 8

  Status_WaitingForRescan indicates that the session is waiting to retry scanning after an error during the previous scanning operation.

• Reconciling = 9

  Status_Reconciling indicates that the session is performing reconciliation.

• StagingAlpha = 10

  Status_StagingAlpha indicates that the session is staging files on alpha.

• StagingBeta = 11

  Status_StagingBeta indicates that the session is staging files on beta.

• Transitioning = 12

  Status_Transitioning indicates that the session is performing transition operations on each endpoint.

• Saving = 13

  Status_Saving indicates that the session is recording synchronization history to disk.

Version specifies a session version, providing default behavior that can vary without affecting existing sessions.

Used in: remote.InitializeSynchronizationRequest, Session

• Invalid = 0

  Invalid is the default session version and represents an unspecfied and invalid version. It is used as a sanity check to ensure that version is set for a session.

• Version1 = 1

  Version1 represents session version 1.

WatchMode specifies the mode for filesystem watching.

Used in: Configuration

• WatchModeDefault = 0

  WatchMode_WatchModeDefault represents an unspecified watch mode. It should be converted to one of the following values based on the desired default behavior.

• WatchModePortable = 1

  WatchMode_WatchModePortable specifies that native recursive watching should be used to monitor paths on systems that support it if those paths fall under the home directory. In these cases, a watch on the entire home directory is established and filtered for events pertaining to the specified path. On all other systems and for all other paths, poll-based watching is used.

• WatchModeForcePoll = 2

  WatchMode_WatchModeForcePoll specifies that only poll-based watching should be used.

• WatchModeNoWatch = 3

  WatchMode_WatchModeNoWatch specifies that no watching should be used (i.e. no events should be generated).