Update API

Table of Contents

• Update Service API

• Scalar Value Types

Update Service API (update/update.proto)

Services

Update

Method Name	Request Type	Response Type	Description
ListGenerations	Empty	ListGenerationsResponse	List installed generations (updates)
Discover	RegistryDiscoverRequest	RegistryDiscoverResponse	Discover available OTA updates in an OCI repository
Changelog	RegistryChangelogRequest	RegistryChangelogResponse	Fetch changelog text for a specific registry tag
Pull	RegistryPullRequest	RegistryPullResponse	Pull OTA update artifacts from an OCI repository
ImageInstall	ImageInstallRequest	ImageInstallResponse	Install image on ghaf-host from a manifest path
InstallCachix	Cachix	SetGenerationResponse	Install a pinned release from Cachix

Messages

AvailableUpdate

Field	Type	Label	Description
Repository	string		OCI repository name
Tag	string		Update tag
Version	string		Update version
Hash	string		Artifact hash

Cachix

Field	Type	Label	Description
Pin	string		Pinned release name
CachixHost	string	optional	API url for cachix
Cache	string		Cachix cache name
Token	string	optional	Optional API token

Empty

Generation

Field	Type	Label	Description
Generation	int32		Numeric generation identifier
Date	string		Build or activation date
NixosVersion	string		NixOS release version
KernelVersion	string		Kernel version string
ConfigurationRevision	string		Configuration revision hash
Specialisations	string	repeated	Enabled specialisations
Current	bool		True if this is the active generation
StorePath	string		Nix store path for the generation

ImageInstallRequest

Field	Type	Label	Description
Manifest	string		Manifest path

ImageInstallResponse

Field	Type	Label	Description
Finished	bool		True when the command completed
Output	string	optional	Standard output from the command
Error	string	optional	Standard error from the command

ListGenerationsResponse

Field	Type	Label	Description
List	Generation	repeated	List of installed generations

RegistryBasicAuth

Field	Type	Label	Description
Username	string		Registry username
Password	string		Registry password

RegistryBearerAuth

Field	Type	Label	Description
Token	string		Registry bearer token

RegistryBlobDownloading

Field	Type	Label	Description
Digest	string		Blob digest
Downloaded	uint64		Downloaded byte count
Total	uint64	optional	Total byte count, if known

RegistryChangelogRequest

Field	Type	Label	Description
Reference	string		OCI reference to inspect
Insecure	bool		Use HTTP instead of HTTPS
Credentials	RegistryCredentials	optional	Optional registry credentials

RegistryChangelogResponse

Field	Type	Label	Description
Changelog	string		Changelog text

RegistryCredentials

Field	Type	Label	Description
Basic	RegistryBasicAuth		Basic auth credentials
Bearer	RegistryBearerAuth		Bearer auth credentials

RegistryDiscoverRequest

Field	Type	Label	Description
Reference	string		OCI reference to search
Insecure	bool		Use HTTP instead of HTTPS
Credentials	RegistryCredentials	optional	Optional registry credentials

RegistryDiscoverResponse

Field	Type	Label	Description
List	AvailableUpdate	repeated	Matching update entries

RegistryPullProgress

Field	Type	Label	Description
PullStarted	RegistryPullStarted		Pull started
BlobDownloading	RegistryBlobDownloading		Blob download progress
BlobVerified	string		Verified blob digest
ManifestWritten	string		Manifest file path
Cancelled	string		Cancellation reason
Done	bool		True when finished

RegistryPullRequest

Field	Type	Label	Description
Reference	string		OCI tag reference to pull
Destination	string		Destination directory
Insecure	bool		Use HTTP instead of HTTPS
Credentials	RegistryCredentials	optional	Optional registry credentials

RegistryPullResponse

Field	Type	Label	Description
Progress	RegistryPullProgress		Progress event
Result	RegistryPullResult		Final result

RegistryPullResult

Field	Type	Label	Description
OutputDir	string		Output directory
ManifestPath	string		Written manifest path

RegistryPullStarted

Field	Type	Label	Description
Reference	string		OCI reference being pulled
Destination	string		Destination directory

SetGenerationRequest

Field	Type	Label	Description
Cachix	Cachix		Cachix-based update payload

SetGenerationResponse

Field	Type	Label	Description
Finished	bool		True when the command completed
Output	string	optional	Standard output from the command
Error	string	optional	Standard error from the command

Scalar Value Types

.proto Type	Notes	Go Type
double		float64
float		float32
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64
uint32	Uses variable-length encoding.	uint32
uint64	Uses variable-length encoding.	uint64
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64
sfixed32	Always four bytes.	int32
sfixed64	Always eight bytes.	int64
bool		bool
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string
bytes	May contain any arbitrary sequence of bytes.	[]byte