The highest tagged major version is v2.

client

package

v1.0.0 Latest Latest Go to latest Published: Oct 1, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation ¶

Overview ¶

Package client is the port an interface uses to work with Cartograph: the web interface, the terminal interface, a bot, a test. It is a Go interface, not a wire protocol. In-process it is the engine itself; over a network it is whatever transport the deployment runs (HTTP and Server-Sent Events over TCP or a UNIX socket today), and the interface never knows which, which is what lets a terminal interface run in the same binary as the engine with no server in between, or across an SSH-forwarded socket, with the same code.

Everything an interface shows comes through this port: the schemas and flows it renders from, the manifests and drafts it edits, the checks and problems it marks, the events it listens to. Nothing in an interface may reach for an HTTP path.

Constants ¶

This section is empty.

Variables ¶

View Source

var ErrNotFound = errors.New("not found")

ErrNotFound is returned by Get and Working for a manifest that is not there (or has no working copy).

View Source

var ErrUnsupported = errors.New("not supported by this transport")

ErrUnsupported is returned by a transport for an operation it does not carry yet.

Functions ¶

This section is empty.

Types ¶

type Check ¶

type Check struct {
	Key     string `json:"key"`
	State   string `json:"state"` // ok, warn, block, note
	Path    string `json:"path"`
	Message string `json:"message"`
	Fix     string `json:"fix,omitempty"` // flow step key
}

Check is one line of a manifest's checks: advice, a warning, or a block, at a field, with the flow step that fixes it.

type Client ¶

type Client interface {
	// Contract: what an interface renders from.
	Kinds(ctx context.Context) ([]string, error)
	Schema(ctx context.Context, kind string) ([]byte, error)
	Flow(ctx context.Context, kind string) (Flow, bool, error)
	Settings(ctx context.Context) (Settings, error)

	// Manifests.
	List(ctx context.Context, kind, query string) ([]Summary, error)
	Get(ctx context.Context, kind, id string) (Manifest, error)
	Working(ctx context.Context, kind, id string) (Manifest, error)
	SaveWorking(ctx context.Context, kind, id string, doc map[string]any) error
	SaveVersion(ctx context.Context, kind, id string, doc map[string]any, reason string) (Version, error)
	Validate(ctx context.Context, kind string, doc map[string]any) ([]Problem, error)
	Checks(ctx context.Context, kind, id string) ([]Check, error)

	// The shared draft (multiplayer).
	Edit(ctx context.Context, kind, id string, ops []merge.Op) (EditResult, error)
	OpsSince(ctx context.Context, kind, id string, after int64) ([]Op, error)
	Subscribe(ctx context.Context, kind, id string) (<-chan Event, error)

	// Identity: who this client acts as, as the engine will record it.
	Actor(ctx context.Context) (string, error)

	Close() error
}

Client is the whole port. A transport implements all of it or returns ErrUnsupported for what it cannot carry yet; the conformance suite in pkg/uiconformance runs over any Client, which is how transports are proven interchangeable.

type EditResult ¶

type EditResult struct {
	Seq       int64
	Conflicts []merge.Conflict
}

EditResult is what Edit answers.

type Event ¶

type Event struct {
	Type  string
	Kind  string
	ID    string
	On    time.Time
	Seq   int64
	Ops   []merge.Op
	Actor string
	Field string
}

Event is what Subscribe delivers: ops appended to a draft, a version saved, state and presence changes. Seq is the position to resume from.

type Flow ¶

type Flow = map[string]any

Flow is a kind's flow document as the contract defines it (contract/flows/flow.schema.json), decoded.

type Manifest ¶

type Manifest struct {
	Kind    string
	ID      string
	Version int // 0 for a working copy
	Doc     map[string]any
	Text    []byte
}

Manifest is a decoded manifest with the text it came from.

type Op ¶

type Op struct {
	Seq int64
	merge.Op
}

Op is a logged op with its position.

type Problem ¶

type Problem struct {
	Path    string `json:"path"`
	Message string `json:"message"`
}

Problem is one refusal or check at a field, the same shape the engine produces everywhere.

type Refused ¶

type Refused struct{ Problems []Problem }

Refused is the error a validating write returns when the engine said no: the problems, landed on their fields. It is a normal outcome an interface shows, not a failure.

func (*Refused) Error ¶

func (r *Refused) Error() string

type Settings ¶

type Settings struct {
	GoalLevels       []string
	ProjectLevelName string
	Operator         string
	Examples         map[string][]string
}

Settings are the organisation's words and defaults.

type Summary ¶

type Summary struct {
	Kind      string
	ID        string
	Name      string
	Version   int
	UpdatedOn time.Time
	Labels    map[string]string
}

Summary is one row of a listing.

type Version ¶

type Version struct {
	Kind   string    `json:"kind"`
	ID     string    `json:"id"`
	Number int       `json:"number"`
	Actor  string    `json:"actor"`
	Reason string    `json:"reason"`
	On     time.Time `json:"on"`
}

Version is one saved version of a manifest.

Source Files ¶

View all Source files

client.go

Directories ¶

Path	Synopsis
inproc Package inproc is the client.Client over an engine in the same process: no wire, no serialisation beyond the codec.	Package inproc is the client.Client over an engine in the same process: no wire, no serialisation beyond the codec.
remote Package remote is the client.Client over the HTTP contract: what an interface uses when the engine is another process, on this machine (a UNIX socket) or elsewhere (TCP, through whatever proxy the deployment runs).	Package remote is the client.Client over the HTTP contract: what an interface uses when the engine is another process, on this machine (a UNIX socket) or elsewhere (TCP, through whatever proxy the deployment runs).

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL