Skip to content

Protocol Documentation

Table of Contents

Top

agntcy/dir/store/v1/store_service.proto

PullReferrerRequest

PullReferrerRequest represents a record with optional OCI artifacts for pull operations.

Field Type Label Description
record_ref agntcy.dir.core.v1.RecordRef Record reference
pull_signature bool Pull signature referrer
pull_public_key bool Pull public key referrer

PullReferrerResponse

PullReferrerResponse is returned after successfully fetching a record referrer.

Field Type Label Description
signature agntcy.dir.sign.v1.Signature Signature to be fetched as a referrer
public_key string Public key to be fetched as a referrer

PushReferrerRequest

PushReferrerRequest represents a record with optional OCI artifacts for push operations.

Field Type Label Description
record_ref agntcy.dir.core.v1.RecordRef Record reference
signature agntcy.dir.sign.v1.Signature Signature to be stored as a referrer for the record
public_key string Public key to be stored as a referrer for the record and uploaded as a file to zot for verification

PushReferrerResponse

PushReferrerResponse

Field Type Label Description
success bool The push process result
error_message string optional Optional error message if push failed

StoreService

Defines an interface for content-addressable storage service for objects.

Max object size: 4MB (to fully fit in a single request) Max metadata size: 100KB

Store service can be implemented by various storage backends, such as local file system, OCI registry, etc.

Middleware should be used to control who can perform these RPCs. Policies for the middleware can be handled via separate service.

Each operation is performed sequentially, meaning that for the N-th request, N-th response will be returned. If an error occurs, the stream will be cancelled.

Method Name Request Type Response Type Description
Push .agntcy.dir.core.v1.Record stream .agntcy.dir.core.v1.RecordRef stream Push performs write operation for given records.
Pull .agntcy.dir.core.v1.RecordRef stream .agntcy.dir.core.v1.Record stream Pull performs read operation for given records.
Lookup .agntcy.dir.core.v1.RecordRef stream .agntcy.dir.core.v1.RecordMeta stream Lookup resolves basic metadata for the records.
Delete .agntcy.dir.core.v1.RecordRef stream .google.protobuf.Empty Remove performs delete operation for the records.
PushReferrer PushReferrerRequest stream PushReferrerResponse stream PushReferrer performs write operation for record referrers.
PullReferrer PullReferrerRequest stream PullReferrerResponse stream PullReferrer performs read operation for record referrers.

Top

agntcy/dir/store/v1/sync_service.proto

BasicAuthCredentials

Supporting credential type definitions

Field Type Label Description
username string
password string

CreateSyncRequest

CreateSyncRequest defines the parameters for creating a new synchronization operation.

Currently supports basic synchronization of all objects from a remote Directory. Future versions may include additional options for filtering and scheduling capabilities.

Field Type Label Description
remote_directory_url string URL of the remote Registry to synchronize from.

This should be a complete URL including protocol and port if non-standard. Examples: - "https://directory.example.com" - "http://localhost:8080" - "https://directory.example.com:9443" | | cids | string | repeated | List of CIDs to synchronize from the remote Directory. If empty, all objects will be synchronized. |

CreateSyncResponse

CreateSyncResponse contains the result of creating a new synchronization operation.

Field Type Label Description
sync_id string Unique identifier for the created synchronization operation. This ID can be used with other SyncService RPCs to monitor and manage the sync.

DeleteSyncRequest

DeleteSyncRequest specifies which synchronization to delete.

Field Type Label Description
sync_id string Unique identifier of the synchronization operation to delete.

DeleteSyncResponse

DeleteSyncResponse

GetSyncRequest

GetSyncRequest specifies which synchronization status to retrieve.

Field Type Label Description
sync_id string Unique identifier of the synchronization operation to query.

GetSyncResponse

GetSyncResponse provides detailed information about a specific synchronization operation.

Field Type Label Description
sync_id string Unique identifier of the synchronization operation.
status SyncStatus Current status of the synchronization operation.
remote_directory_url string URL of the remote Directory node being synchronized from.
created_time string Timestamp when the synchronization operation was created in the RFC3339 format. Specs: https://www.rfc-editor.org/rfc/rfc3339.html
last_update_time string Timestamp of the most recent status update for this synchronization in the RFC3339 format.

ListSyncsItem

ListSyncItem represents a single synchronization in the list of all syncs.

Field Type Label Description
sync_id string Unique identifier of the synchronization operation.
status SyncStatus Current status of the synchronization operation.
remote_directory_url string URL of the remote Directory being synchronized from.

ListSyncsRequest

ListSyncsRequest specifies parameters for listing synchronization operations.

Field Type Label Description
limit uint32 optional Optional limit on the number of results to return.
offset uint32 optional Optional offset for pagination of results.

RequestRegistryCredentialsRequest

Field Type Label Description
requesting_node_id string Identity of the requesting node For example: spiffe://example.org/service/foo

RequestRegistryCredentialsResponse

Field Type Label Description
success bool Success status of the credential negotiation
error_message string Error message if negotiation failed
remote_registry_url string URL of the remote Registry being synchronized from.
basic_auth BasicAuthCredentials CertificateCredentials certificate = 5;

SyncStatus

SyncStatus enumeration defines the possible states of a synchronization operation.

Name Number Description
SYNC_STATUS_UNSPECIFIED 0 Default/unset status - should not be used in practice
SYNC_STATUS_PENDING 1 Sync operation has been created but not yet started
SYNC_STATUS_IN_PROGRESS 2 Sync operation is actively discovering and transferring objects
SYNC_STATUS_FAILED 3 Sync operation encountered an error and stopped
SYNC_STATUS_DELETE_PENDING 4 Sync operation has been marked for deletion but cleanup not yet started
SYNC_STATUS_DELETED 5 Sync operation has been successfully deleted and cleaned up

SyncService

SyncService provides functionality for synchronizing objects between Directory nodes.

This service enables one-way synchronization from a remote Directory node to the local node, allowing distributed Directory instances to share and replicate objects. The service supports both on-demand synchronization and tracking of sync operations through their lifecycle.

Method Name Request Type Response Type Description
CreateSync CreateSyncRequest CreateSyncResponse CreateSync initiates a new synchronization operation from a remote Directory node.

The operation is non-blocking and returns immediately with a sync ID that can be used to track progress and manage the sync operation. | | ListSyncs | ListSyncsRequest | ListSyncsItem stream | ListSyncs returns a stream of all sync operations known to the system.

This includes active, completed, and failed synchronizations. | | GetSync | GetSyncRequest | GetSyncResponse | GetSync retrieves detailed status information for a specific synchronization. | | DeleteSync | DeleteSyncRequest | DeleteSyncResponse | DeleteSync removes a synchronization operation from the system. | | RequestRegistryCredentials | RequestRegistryCredentialsRequest | RequestRegistryCredentialsResponse | RequestRegistryCredentials requests registry credentials between two Directory nodes.

This RPC allows a requesting node to authenticate with this node and obtain temporary registry credentials for secure Zot-based synchronization. |

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)