Help us shape the future of Go! Take the 2026 Go Developer Survey

dto

package
v0.70.1 Latest Latest
Warning

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

 Go to latest Published: Oct 22, 2026 License: MIT Imports: 13 Imported by: 3

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrQueryRevisionConflict  = errors.New("query revision conflict")
	ErrBranchHeadConflict     = errors.New("branch head conflict")
	ErrOperationConflict      = errors.New("operation id was used for another mutation")
	ErrUnsupportedCapability  = errors.New("project store does not support this operation")
	ErrInitializationRequired = errors.New("repository needs an initialized branch")
)

These errors have stable meanings across local, Firestore and Git adapters. HTTP transports map conflicts to 409 and unsupported capabilities to 400.

View Source 
var ErrAssetRevisionConflict = errors.New("project asset revision conflict")

Functions

func EnvironmentStateDigest added in v0.67.0 

func EnvironmentStateDigest(state EnvironmentState) (string, error)

EnvironmentStateDigest binds canonical safe membership, raw saved order and resolved order.

func ProjectAssetRevision added in v0.62.0 

func ProjectAssetRevision(kind string, asset any) (string, error)

ProjectAssetRevision qualifies a content digest by its owning wire type. Callers validate the actual asset before deriving its revision.

func ValidateEnvironmentJSONUnicode added in v0.67.0 

func ValidateEnvironmentJSONUnicode(body []byte) error

ValidateEnvironmentJSONUnicode refuses malformed UTF-8 and escaped unpaired surrogates.

func ValidateProjectID added in v0.40.0 

func ValidateProjectID(id string) error

ValidateProjectID applies DataTug's project-id rules. It is exported so a caller that has to choose an id — a CLI's new-project form, say — can check one without building a whole CreateProjectRequest around it.

A project id is both a DALgo key segment and, under a file-backed store, a directory name, so it is restricted to what is unambiguous in both:

  • 1 to maxProjectIDLength characters;
  • lower-case ASCII letters, digits, "-" and "_" only. Upper case is refused rather than folded, because a store cloned onto a case-insensitive file system (macOS, Windows) would collapse two ids that differ only in case into one directory;
  • the first and last character must be a letter or a digit, so an id never starts or ends with "-" or "_".

The charset rules out every path separator, "." and "..", whitespace and control characters, so no id can escape or rename its own directory.

Types

type AssetWriteCondition added in v0.62.0 

type AssetWriteCondition struct {
	ProjectRef
	Environment string `json:"environment"`
	OperationID string `json:"operationId"`
	IfNoneMatch bool   `json:"ifNoneMatch,omitempty"`
	IfMatch     string `json:"ifMatch,omitempty"`
}

func (AssetWriteCondition) Validate added in v0.62.0 

func (v AssetWriteCondition) Validate() error

type CompareBranchesRequest added in v0.44.0 

type CompareBranchesRequest struct {
	ProjectRef
	SourceBranch string `json:"sourceBranch"`
	SourceHead   string `json:"sourceHead"`
	TargetBranch string `json:"targetBranch"`
	TargetHead   string `json:"targetHead"`
}

CompareBranchesRequest pins both sides so a diff cannot silently change between the user's review and subsequent merge request.

type CreateBranchRequest added in v0.44.0 

type CreateBranchRequest struct {
	ProjectRef
	Branch      string `json:"branch"`
	FromBranch  string `json:"fromBranch"`
	SourceHead  string `json:"sourceHead"`
	OperationID string `json:"operationId"`
}

CreateBranchRequest creates a branch only while SourceHead still matches.

type CreateEnvironmentRequest added in v0.67.0 

type CreateEnvironmentRequest struct {
	EnvironmentMutation
	Name string `json:"name"`
}

type CreateFolder 

type CreateFolder struct {
	ProjectRef
	Name string `json:"name"`
	Path string `json:"path"`
	Note string `json:"note,omitempty"`
}

CreateFolder defines request for folder creation

func (CreateFolder) Validate 

func (v CreateFolder) Validate() error

Validate returns error if not valid

type CreateProjectItemRequest 

type CreateProjectItemRequest struct {
	Title string `json:"title"`
}

type CreateProjectRequest 

type CreateProjectRequest struct {
	StoreID string `json:"store"`

	// ID is the id of the project to create. It is supplied by the caller,
	// never derived from the title: it addresses the project for the rest of
	// its life — a key segment, and a directory name under a file-backed
	// store — so the caller, not the storage, owns it. See
	// ValidateProjectID for the rules it must satisfy.
	ID string `json:"id"`

	Title string `json:"title"`
}

CreateProjectRequest request

func (CreateProjectRequest) Validate 

func (v CreateProjectRequest) Validate() error

type CreateQuery 

type CreateQuery struct {
	ProjectRef
	Folder string                         `json:"folder"`
	Query  datatug.QueryDefWithFolderPath `json:"query"`
}

type EnvironmentBrief added in v0.67.0 

type EnvironmentBrief struct {
	ID           string                   `json:"id"`
	Title        string                   `json:"title,omitempty"`
	Access       string                   `json:"access,omitempty"`
	Presentation *EnvironmentPresentation `json:"presentation,omitempty"`
}

EnvironmentBrief excludes connection and server declarations.

type EnvironmentCapabilities added in v0.67.0 

type EnvironmentCapabilities struct {
	CanReadOrder         bool              `json:"canReadOrder"`
	CanWriteOrder        bool              `json:"canWriteOrder"`
	CanCreateEnvironment bool              `json:"canCreateEnvironment"`
	Reasons              map[string]string `json:"reasons,omitempty"`
}

type EnvironmentMutation added in v0.67.0 

type EnvironmentMutation struct {
	Scope       EnvironmentScope `json:"scope"`
	IfRevision  string           `json:"ifRevision"`
	OperationID string           `json:"operationId"`
}

type EnvironmentOperationResult added in v0.67.0 

type EnvironmentOperationResult struct {
	OperationID      string   `json:"operationId"`
	Kind             string   `json:"kind"`
	PayloadDigest    string   `json:"payloadDigest"`
	AcceptedAt       string   `json:"acceptedAt"`
	ReplayUntil      string   `json:"replayUntil"`
	EnvironmentID    string   `json:"environmentId,omitempty"`
	EnvironmentOrder []string `json:"environmentOrder,omitempty"`
	AfterStateDigest string   `json:"afterStateDigest"`
	Status           string   `json:"status"`
}

func (EnvironmentOperationResult) MarshalJSON added in v0.67.0 

func (v EnvironmentOperationResult) MarshalJSON() ([]byte, error)

MarshalJSON preserves an accepted empty order on a save receipt.

type EnvironmentOperationStatusRequest added in v0.67.0 

type EnvironmentOperationStatusRequest struct {
	Scope       EnvironmentScope `json:"scope"`
	OperationID string           `json:"operationId"`
}

type EnvironmentPresentation added in v0.67.0 

type EnvironmentPresentation struct {
	Label string `json:"label,omitempty"`
	Icon  string `json:"icon,omitempty"`
	Tone  string `json:"tone,omitempty"`
}

type EnvironmentScope added in v0.67.0 

type EnvironmentScope struct {
	StoreID        string  `json:"storeId"`
	ProjectID      string  `json:"projectId"`
	SpaceID        *string `json:"spaceID,omitempty"`
	ProjectAPI     *string `json:"projectApi,omitempty"`
	Branch         *string `json:"branch,omitempty"`
	AuthorityID    string  `json:"authorityId"`
	ResolvedBranch *string `json:"resolvedBranch,omitempty"`
	RepositoryID   *int64  `json:"repositoryId,omitempty"`
	Owner          *string `json:"owner,omitempty"`
	Repository     *string `json:"repository,omitempty"`
	Folder         *string `json:"folder,omitempty"`
}

EnvironmentScope preserves requested qualifiers alongside resolved authority.

type EnvironmentState added in v0.67.0 

type EnvironmentState struct {
	Contract     string                  `json:"contract"`
	Scope        EnvironmentScope        `json:"scope"`
	ScopeBinding string                  `json:"scopeBinding"`
	Environments []EnvironmentBrief      `json:"environments"`
	SavedOrder   []string                `json:"savedOrder"`
	Order        []string                `json:"order"`
	NeedsRepair  bool                    `json:"needsRepair"`
	Revision     string                  `json:"revision"`
	Capabilities EnvironmentCapabilities `json:"capabilities"`
}

type GetQueryRequest added in v0.44.0 

type GetQueryRequest struct {
	ProjectRef
	ID     string `json:"id"`
	Branch string `json:"branch,omitempty"`
}

GetQueryRequest loads the complete query pair at an explicit selected Git branch. Firestore rejects Branch; local and GitHub stores require it when branch mode is enabled.

type GetQueryResponse added in v0.44.0 

type GetQueryResponse = SaveQueryResponse

type GetServerDatabasesRequest 

type GetServerDatabasesRequest struct {
	Project     string `json:"proj"`
	Environment string `json:"env"`
	datatug.ServerRef
	Credentials *datatug.Credentials `json:"credentials"`
}

GetServerDatabasesRequest input for /dbserver/databases API

func (GetServerDatabasesRequest) Validate 

func (v GetServerDatabasesRequest) Validate() error

Validate returns error if not valid

type MergeBranchesRequest added in v0.44.0 

type MergeBranchesRequest struct {
	CompareBranchesRequest
	OperationID string `json:"operationId"`
}

MergeBranchesRequest asks the Git provider to merge the reviewed heads. An adapter must return an explicit pending/proposal result when branch protection requires a PR; it must never report that as merged.

type MergeBranchesResponse added in v0.44.0 

type MergeBranchesResponse struct {
	State       string `json:"state"` // merged | proposal | conflict | pending
	TargetHead  string `json:"targetHead,omitempty"`
	ProposalURL string `json:"proposalUrl,omitempty"`
}

type OperationReceipt added in v0.44.0 

type OperationReceipt struct {
	Scope         OperationScope
	OperationID   string
	PayloadDigest string
	Result        SaveQueryResponse
}

OperationReceipt describes a previously committed mutation. A provider persists it durably and rechecks actor authorization before replaying it.

func (OperationReceipt) MatchSaveRetry added in v0.44.0 

func (r OperationReceipt) MatchSaveRetry(scope OperationScope, request SaveQueryRequest) error

MatchSaveRetry rejects a reused operation ID with a different scope or payload. Authorization must already have been rechecked by the caller.

type OperationScope added in v0.44.0 

type OperationScope struct {
	ActorID   string
	StoreID   string
	ProjectID string
	Branch    string
	Kind      string
}

OperationScope is derived by the server from a verified actor and resolved store. A browser-supplied actor ID must never be trusted here.

type ProjRecordsetSummary 

type ProjRecordsetSummary struct {
	datatug.ProjectItem
	Columns    []string                `json:"columns,omitempty"`
	Recordsets []*ProjRecordsetSummary `json:"recordsets,omitempty"`
}

ProjRecordsetSummary holds summary info about recordset definition

type ProjectBranchRef added in v0.44.0 

type ProjectBranchRef struct {
	ProjectRef
	Branch string `json:"branch"`
}

ProjectBranchRef addresses one named Git branch. Cloud project stores do not support branches and must return an unsupported-capability response.

type ProjectCapabilities added in v0.44.0 

type ProjectCapabilities struct {
	SemanticModel  bool `json:"semanticModel"`
	QueryRead      bool `json:"queryRead"`
	QuerySave      bool `json:"querySave"`
	Branches       bool `json:"branches"`
	BranchMerge    bool `json:"branchMerge"`
	ReviewedCommit bool `json:"reviewedCommit"`
	PullCurrent    bool `json:"pullCurrent"`
	PushCurrent    bool `json:"pushCurrent"`
}

ProjectCapabilities tells clients which controls a selected store offers; the server must still authorize every individual operation.

type ProjectItemRef 

type ProjectItemRef struct {
	ProjectRef
	ID string
}

ProjectItemRef holds ProjectRef & ID parameters

func (ProjectItemRef) Validate 

func (v ProjectItemRef) Validate() error

Validate returns error if not valid

type ProjectQueryAdapter added in v0.44.0 

type ProjectQueryAdapter interface {
	Capabilities(context.Context, ProjectRef) (ProjectCapabilities, error)
	GetQuery(context.Context, GetQueryRequest) (*GetQueryResponse, error)
	SaveQuery(context.Context, OperationScope, SaveQueryRequest) (*SaveQueryResponse, error)
}

ProjectQueryAdapter is the storage-neutral seam for DataTug Cloud's Firestore/GitHub adapters and the CLI's local filestore adapter. Scope is created from the authenticated serving principal; implementations check authorization on every call, including operation-receipt replay.

type ProjectRef 

type ProjectRef struct {
	StoreID   string `json:"storage"`
	ProjectID string `json:"project"`
}

ProjectRef holds storage & project parameters

func (ProjectRef) Validate 

func (v ProjectRef) Validate() error

Validate returns error if not valid

type SaveBoardRequest added in v0.62.0 

type SaveBoardRequest struct {
	AssetWriteCondition
	Board datatug.Board `json:"board"`
}

func (SaveBoardRequest) Validate added in v0.62.0 

func (v SaveBoardRequest) Validate() error

type SaveBoardResponse added in v0.62.0 

type SaveBoardResponse struct {
	Board    datatug.Board `json:"board"`
	Revision string        `json:"revision"`
	Receipt  string        `json:"receipt"`
}

type SaveEntityRequest added in v0.62.0 

type SaveEntityRequest struct {
	AssetWriteCondition
	Entity datatug.Entity `json:"entity"`
}

func (SaveEntityRequest) Validate added in v0.62.0 

func (v SaveEntityRequest) Validate() error

type SaveEntityResponse added in v0.62.0 

type SaveEntityResponse struct {
	Entity   datatug.Entity `json:"entity"`
	Revision string         `json:"revision"`
	Receipt  string         `json:"receipt"`
}

type SaveEnvironmentOrderRequest added in v0.67.0 

type SaveEnvironmentOrderRequest struct {
	EnvironmentMutation
	EnvironmentOrder []string `json:"environmentOrder"`
}

type SaveQueryRequest added in v0.44.0 

type SaveQueryRequest struct {
	ProjectRef
	Branch             string                         `json:"branch,omitempty"`
	ExpectedBranchHead string                         `json:"expectedBranchHead,omitempty"`
	OperationID        string                         `json:"operationId"`
	IfNoneMatch        bool                           `json:"ifNoneMatch,omitempty"`
	IfMatch            string                         `json:"ifMatch,omitempty"`
	Query              datatug.QueryDefWithFolderPath `json:"query"`
}

SaveQueryRequest is the additive, storage-neutral query write contract used by the local API and DataTug Cloud. Existing create_query and update_query contracts remain unchanged. A Git store requires Branch and ExpectedBranchHead; a non-Git store rejects those fields at the adapter. OperationID lets an adapter recover a committed result after a retry.

func (SaveQueryRequest) PayloadDigest added in v0.44.0 

func (v SaveQueryRequest) PayloadDigest() (string, error)

PayloadDigest binds an operation receipt to the complete immutable save intent, including its selected branch/head and query body. OperationID is intentionally excluded so retries with the same intent have one digest. Call Validate before computing it; this method does not authorize a write.

func (SaveQueryRequest) Validate added in v0.44.0 

func (v SaveQueryRequest) Validate() error

Validate checks provider-independent inputs. Store adapters additionally validate the selected branch, repository, revision and project authority.

type SaveQueryResponse added in v0.44.0 

type SaveQueryResponse struct {
	Query      datatug.QueryDefWithFolderPath `json:"query"`
	Revision   string                         `json:"revision"`
	BranchHead string                         `json:"branchHead,omitempty"`
}

SaveQueryResponse reports the bytes persisted and the revision to send as IfMatch on the next write. A Git adapter also returns the resulting branch head; both revisions are opaque to clients.

type UpdateQuery 

type UpdateQuery struct {
	ProjectItemRef
	Query datatug.QueryDefWithFolderPath `json:"query"`
}

Source Files

View all Source files

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.