cloudclient

package
v0.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 18, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package cloudclient 是 Pinax CLI 访问 Pinax Cloud Sync MLP 服务端 REST 合同的客户端。

MLP 合同（pinax-cloud-sync-mlp）使用 vault_id 术语，公开路由：

  • POST /v1/auth/bootstrap 账户与设备会话 bootstrap
  • GET /v1/auth/principal 当前登录主体（login state）
  • POST /v1/vaults 创建 vault
  • POST /v1/vaults/{vault_id}/link 设备绑定 vault
  • GET /v1/vaults/{vault_id}/changes?since=<revision_id>
  • POST /v1/vaults/{vault_id}/blobs:batch-check
  • POST /v1/vaults/{vault_id}/blobs:sign-upload
  • PUT /v1/vaults/{vault_id}/blobs/{blob_id}
  • GET /v1/vaults/{vault_id}/blobs/{blob_id}
  • GET /v1/vaults/{vault_id}/head 当前 head revision/manifest
  • POST /v1/vaults/{vault_id}/revisions CAS commit

所有写操作携带稳定 error code、idempotency、device 与脱敏要求；Cloud 不读取明文。

Index

Constants

View Source 
const (
	CodeUnauthenticated    = "UNAUTHENTICATED"
	CodeDeviceRevoked      = "DEVICE_REVOKED"
	CodeForbiddenScope     = "FORBIDDEN_SCOPE"
	CodeRevisionConflict   = "REVISION_CONFLICT"
	CodeRevisionNotFound   = "REVISION_NOT_FOUND"
	CodeValidationFailed   = "VALIDATION_FAILED"
	CodeBlobMissing        = "BLOB_MISSING"
	CodeBlobTooLarge       = "BLOB_TOO_LARGE"
	CodeBlobHashMismatch   = "BLOB_HASH_MISMATCH"
	CodeBlobSizeMismatch   = "BLOB_SIZE_MISMATCH"
	CodeUploadPlanExpired  = "UPLOAD_PLAN_EXPIRED"
	CodeBackendUnavailable = "BACKEND_UNAVAILABLE"
	CodeTransportError     = "TRANSPORT_ERROR"
	CodeCloudHTTPError     = "CLOUD_HTTP_ERROR"
)

MLP 稳定 error code（大写，与服务端 pinax-cloud-sync-mlp 合同一致）。

Variables

This section is empty.

Functions

func IsCode 

func IsCode(err error, code string) bool

func IsRevisionConflict 

func IsRevisionConflict(err error) bool

IsRevisionConflict 判断错误是否为服务端 CAS 冲突（REVISION_CONFLICT）。

Types

type BlobCheckResult 

type BlobCheckResult struct {
	MissingBlobIDs []string   `json:"missing_blob_ids"`
	Present        []BlobFact `json:"present"`
}

type BlobEnvelope 

type BlobEnvelope struct {
	SchemaVersion string `json:"schema_version"`
	Alg           string `json:"alg"`
	KeyID         string `json:"key_id"`
	Nonce         string `json:"nonce,omitempty"`
	Ciphertext    string `json:"ciphertext"`
	PlainSHA256   string `json:"plain_sha256"`
}

type BlobFact 

type BlobFact struct {
	BlobID   string `json:"blob_id"`
	BlobHash string `json:"blob_hash"`
	Size     int64  `json:"size"`
}

type BootstrapResult 

type BootstrapResult struct {
	AccountID string `json:"account_id"`
	DeviceID  string `json:"device_id"`
	VaultID   string `json:"vault_id,omitempty"`
	TokenRef  string `json:"token_ref,omitempty"`
	Scope     string `json:"scope,omitempty"`
}

BootstrapResult 是 bootstrap/login 成功后返回的会话事实；不含 raw token。

type ChangesResult 

type ChangesResult struct {
	Revisions []Revision  `json:"revisions"`
	Objects   []ObjectRef `json:"objects"`
	HasMore   bool        `json:"has_more"`
}

ChangesResult 是 GET /changes?since=<revision_id> 的返回。

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func New 

func New(cfg Config) (*Client, error)

func (*Client) BatchCheckBlobs 

func (c *Client) BatchCheckBlobs(ctx context.Context, blobIDs []string) (BlobCheckResult, error)

func (*Client) Bootstrap 

func (c *Client) Bootstrap(ctx context.Context, bootstrapToken, deviceLabel string) (BootstrapResult, error)

Bootstrap 调用 POST /v1/auth/bootstrap 完成单账户自托管 bootstrap。 返回的 BootstrapResult 只含脱敏事实；token 由调用方写入 secret ref，不进入日志。

func (*Client) Changes 

func (c *Client) Changes(ctx context.Context, since string) (ChangesResult, error)

Changes 调用 GET /v1/vaults/{vault_id}/changes?since=<revision_id> 获取增量对象引用。

func (*Client) CommitRevision 

func (c *Client) CommitRevision(ctx context.Context, req CommitRequest) (CommitResponse, error)

func (*Client) CreateVault 

func (c *Client) CreateVault(ctx context.Context, cryptoMode string) (VaultLinkFacts, error)

CreateVault 调用 POST /v1/vaults 创建 vault。

func (*Client) CurrentPrincipal 

func (c *Client) CurrentPrincipal(ctx context.Context) (Principal, error)

CurrentPrincipal 调用 GET /v1/auth/principal 返回当前登录主体脱敏事实。

func (*Client) CurrentRevision 

func (c *Client) CurrentRevision(ctx context.Context) (Revision, error)

func (*Client) DownloadBlob 

func (c *Client) DownloadBlob(ctx context.Context, blobID string) (BlobEnvelope, error)

func (*Client) Health 

func (c *Client) Health(ctx context.Context) (Health, error)

func (*Client) LinkVault 

func (c *Client) LinkVault(ctx context.Context, vaultID string) (VaultLinkFacts, error)

LinkVault 调用 POST /v1/vaults/{vault_id}/link 绑定当前设备到 vault。

func (*Client) SignUpload 

func (c *Client) SignUpload(ctx context.Context, blobID, blobHash string, size int64, contentType string) (UploadPlan, error)

SignUpload 调用 POST /v1/vaults/{vault_id}/blobs:sign-upload 获取服务端拥有的上传计划。

func (*Client) UploadBlob 

func (c *Client) UploadBlob(ctx context.Context, blobID string, envelope BlobEnvelope) error

func (*Client) VaultID 

func (c *Client) VaultID() string

VaultID 返回客户端绑定的 vault id。

type CommitRequest 

type CommitRequest struct {
	BaseRevision   string      `json:"base_revision"`
	RevisionID     string      `json:"revision_id,omitempty"`
	ManifestBlobID string      `json:"manifest_blob_id"`
	ObjectRefs     []ObjectRef `json:"object_refs,omitempty"`
	DeviceID       string      `json:"device_id,omitempty"`
	IdempotencyKey string      `json:"-"`
}

type CommitResponse 

type CommitResponse struct {
	RevisionID     string `json:"revision_id"`
	ManifestBlobID string `json:"manifest_blob_id"`
}

type Config 

type Config struct {
	Endpoint   string
	VaultID    string
	DeviceID   string
	Token      string
	HTTPClient *http.Client
}

type Error 

type Error struct {
	Code       string
	Message    string
	Retryable  bool
	StatusCode int
}

func (*Error) Error 

func (e *Error) Error() string

type ErrorBody 

type ErrorBody struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	Retryable bool   `json:"retryable"`
}

type Health 

type Health struct {
	Status          string `json:"status"`
	ContractVersion string `json:"contract_version,omitempty"`
}

type ObjectRef 

type ObjectRef struct {
	PathHash  string `json:"path_hash"`
	BlobID    string `json:"blob_id,omitempty"`
	BlobHash  string `json:"blob_hash"`
	Size      int64  `json:"size"`
	SizeBytes int64  `json:"size_bytes,omitempty"`
	Deleted   bool   `json:"deleted"`
}

ObjectRef 是 changes cursor 返回的对象引用；使用 path_hash/blob_hash 而非明文路径。

type Principal 

type Principal struct {
	AccountID string `json:"account_id"`
	DeviceID  string `json:"device_id"`
	VaultID   string `json:"vault_id,omitempty"`
	TokenRef  string `json:"token_ref,omitempty"`
	Scope     string `json:"scope,omitempty"`
}

Principal 描述当前登录主体的脱敏事实，用于 cloud login/doctor/sync status。

type Revision 

type Revision struct {
	RevisionID     string `json:"revision_id"`
	ManifestBlobID string `json:"manifest_blob_id"`
}

type Transport 

type Transport struct {
	// contains filtered or unexported fields
}

Transport 把 cloudclient.Client（MLP REST）适配为 cloudsync.Transport， 让 Pinax 同步引擎统一通过 server transport 跑 push/pull。 remote_write 只在服务端 CAS commit 成功后才为 true（见 CommitRevision）。

func NewTransport 

func NewTransport(client *Client) *Transport

func (*Transport) BatchCheck 

func (t *Transport) BatchCheck(ctx context.Context, blobIDs []string) (cloudsync.BatchCheckResult, error)

func (*Transport) CommitRevision 

func (t *Transport) CommitRevision(ctx context.Context, req cloudsync.CommitRequest) (cloudsync.CommitResult, error)

CommitRevision 只在服务端 CAS commit 成功后返回 RemoteWrite=true。 服务端返回 REVISION_CONFLICT 时透传错误，RemoteWrite 保持 false。

func (*Transport) CurrentHead 

func (t *Transport) CurrentHead(ctx context.Context, vaultID string) (cloudsync.Head, error)

func (*Transport) GetBlob 

func (t *Transport) GetBlob(ctx context.Context, blobID string) (cloudsync.Envelope, error)

func (*Transport) GetManifest 

func (t *Transport) GetManifest(ctx context.Context, blobID string) (cloudsync.Envelope, error)

func (*Transport) PutBlob 

func (t *Transport) PutBlob(ctx context.Context, blobID string, envelope cloudsync.Envelope) error

func (*Transport) PutBlobWithEnvelopeMetadata 

func (t *Transport) PutBlobWithEnvelopeMetadata(ctx context.Context, blobID string, envelope cloudsync.Envelope) (string, int64, error)

func (*Transport) PutBlobWithMetadata 

func (t *Transport) PutBlobWithMetadata(ctx context.Context, blobID, blobHash string, sizeBytes int64, envelope cloudsync.Envelope) error

func (*Transport) PutManifest 

func (t *Transport) PutManifest(ctx context.Context, blobID string, envelope cloudsync.Envelope) error

func (*Transport) RegisterBlobMetadata 

func (t *Transport) RegisterBlobMetadata(ctx context.Context, blobID, blobHash string, sizeBytes int64) error

type UploadPlan 

type UploadPlan struct {
	BlobID    string            `json:"blob_id"`
	ObjectKey string            `json:"object_key"`
	Method    string            `json:"method"`
	URL       string            `json:"url"`
	Headers   map[string]string `json:"headers,omitempty"`
	ExpiresAt string            `json:"expires_at,omitempty"`
}

UploadPlan 是 sign-upload 返回的服务端拥有对象上传计划。

type VaultLinkFacts 

type VaultLinkFacts struct {
	VaultID         string `json:"vault_id"`
	CryptoMode      string `json:"crypto_mode"`
	CurrentRevision string `json:"current_revision,omitempty"`
}

VaultLinkFacts 是 vault create/link 返回的有界事实。

Source Files

View all Source files

Directories

Path Synopsis
Package mlptest 提供 Pinax Cloud Sync MLP REST 合同的内存 HTTP 测试服务端。
 Package mlptest 提供 Pinax Cloud Sync MLP REST 合同的内存 HTTP 测试服务端。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.