server

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package server implements the AgentStore HTTP server. One server process serves multiple repos; each repo is an independent store under the data directory.

Index

Constants

View Source 
const (
	EventFileCreated  = "file.created"
	EventFileModified = "file.modified"
	EventFileDeleted  = "file.deleted"
	EventCommitPushed = "commit.pushed"
)

Event types, all derived from accepted commits.

View Source 
const DrainTimeout = 30 * time.Second

DrainTimeout is the maximum time Shutdown waits for in-flight requests.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuthzResponse 

type AuthzResponse struct {
	Admin     bool `json:"admin"`
	RootOwner bool `json:"root_owner"`
}

AuthzResponse reports the caller's repo-wide authority (used by the client to gate whole-repo operations like `checkout .`).

type CommitFileJSON 

type CommitFileJSON struct {
	Path            string `json:"path"`
	ObjectHash      string `json:"object_hash,omitempty"`
	Size            int64  `json:"size,omitempty"`
	ChangeType      string `json:"change_type"`
	BasedOnCommitID string `json:"based_on_commit_id,omitempty"`
}

CommitFileJSON is one file entry in a CommitJSON.

type CommitJSON 

type CommitJSON struct {
	ID        string           `json:"id,omitempty"`
	Seq       int64            `json:"seq"`
	Message   string           `json:"message,omitempty"`
	AuthorID  string           `json:"author_id,omitempty"`
	CreatedAt int64            `json:"created_at,omitempty"`
	Parents   []string         `json:"parents,omitempty"`
	Files     []CommitFileJSON `json:"files,omitempty"`
	Redacted  bool             `json:"redacted,omitempty"`
}

CommitJSON is the serialised form of a commit in GET /<repo>/commits. A fully-inaccessible commit is delivered as a stub: {seq, redacted:true}.

type ConflictDetail 

type ConflictDetail struct {
	Conflicts []ConflictFile `json:"conflicts"`
}

ConflictDetail is included in a push_conflict ErrorResponse.

type ConflictFile 

type ConflictFile struct {
	Path                string `json:"path"`
	CurrentHeadCommitID string `json:"current_head_commit_id"`
}

ConflictFile names a file that blocked a push and its current server head.

type CreateRepoResponse 

type CreateRepoResponse struct {
	Repo string `json:"repo"`
}

CreateRepoResponse is returned by POST /<repo>.

type DirectoryEntryResponse 

type DirectoryEntryResponse struct {
	PrincipalID string `json:"principal_id"`
	Username    string `json:"username"`
	PublicKey   string `json:"public_key"`
}

DirectoryEntryResponse is one entry from the open GET /_directory plane: the single-row body of a ?username= lookup (used by `bind` to resolve a username to its principal_id + public key) and, in a list, one row of the no-param browse (used by `principals list --remote`). The directory is public, so the endpoint is unauthenticated.

type ErrorResponse 

type ErrorResponse struct {
	Code    string          `json:"code"`
	Message string          `json:"message"`
	Detail  *ConflictDetail `json:"detail,omitempty"`
}

ErrorResponse is the body of any non-2xx response.

type EventJSON 

type EventJSON struct {
	Cursor     int64    `json:"cursor"`
	Type       string   `json:"type"`
	Timestamp  int64    `json:"timestamp"`
	CommitID   string   `json:"commit_id"`
	AuthorID   string   `json:"author_id"`
	Path       string   `json:"path,omitempty"`
	ObjectHash string   `json:"object_hash,omitempty"`
	Size       int64    `json:"size,omitempty"`
	Message    string   `json:"message,omitempty"`
	Paths      []string `json:"paths,omitempty"`
}

EventJSON is a single event delivered over the watch WebSocket. A file.* event carries Path/ObjectHash/Size; a commit.pushed carries Message/Paths. All events of one commit share the same Cursor (the commit's seq).

type ExportResponse 

type ExportResponse struct {
	Grants []MirrorGrant `json:"grants"`
	Roles  []MirrorRole  `json:"roles"`
}

ExportResponse is the body of GET /<repo>/export (admin only): the access control state not delivered by ordinary clone (grants + roles).

type GrantRequest 

type GrantRequest struct {
	Principal  string `json:"principal"`  // username
	Permission string `json:"permission"` // read|write|owner
	Path       string `json:"path"`       // exact path or prefix pattern
}

GrantRequest is the body of POST /<repo>/grants.

type HeadJSON 

type HeadJSON struct {
	Path       string `json:"path"`
	CommitID   string `json:"commit_id"`
	ObjectHash string `json:"object_hash,omitempty"` // "" if deleted
	ChangeType string `json:"change_type"`
}

HeadJSON is one entry in the GET /<repo>/heads response.

type MemberRequest 

type MemberRequest struct {
	Username string `json:"username"`
}

MemberRequest is the body of POST/DELETE /<repo>/members and /admins.

type MirrorGrant 

type MirrorGrant struct {
	PrincipalID string `json:"principal_id"`
	PathPattern string `json:"path_pattern"`
	Permission  string `json:"permission"`
	GrantedBy   string `json:"granted_by"`
}

MirrorGrant / MirrorRole carry access control rows verbatim in a mirror or export.

type MirrorObject 

type MirrorObject struct {
	Hash    string `json:"hash"`
	Content []byte `json:"content"` // base64 in JSON
}

MirrorObject is one content object carried inline in a mirror.

type MirrorRename 

type MirrorRename struct {
	PrincipalID string `json:"principal_id"`
	From        string `json:"from"`
	To          string `json:"to"`
}

MirrorRename records a roster principal whose username collided with a different principal already in the target directory and was auto-renamed during seeding (e.g. "alice" -> "alice-2").

type MirrorRequest 

type MirrorRequest struct {
	Principals []PrincipalJSON `json:"principals"` // roster (also seeds the target directory)
	Objects    []MirrorObject  `json:"objects"`
	Commits    []CommitJSON    `json:"commits"`
	Grants     []MirrorGrant   `json:"grants"`
	Roles      []MirrorRole    `json:"roles"`
}

MirrorRequest is the full repo state uploaded by `push --mirror` to an empty target. Commits are in seq order; ids and seqs are preserved verbatim.

type MirrorResponse 

type MirrorResponse struct {
	Repo        string         `json:"repo"`
	PrincipalID string         `json:"principal_id"`
	Username    string         `json:"username"`
	Renames     []MirrorRename `json:"renames,omitempty"`
}

MirrorResponse is returned to the admin who performed the move. It reports the signer's resulting identity on the new server (principal_id is preserved; the username may have been auto-renamed) plus the full set of roster renames, so the admin can tell affected members which username to `bind`.

type MirrorRole 

type MirrorRole struct {
	PrincipalID string `json:"principal_id"`
	Role        string `json:"role"`
	GrantedBy   string `json:"granted_by"`
}

type PermissionEntry 

type PermissionEntry struct {
	Principal  string `json:"principal"`
	Permission string `json:"permission"`
	Path       string `json:"path"`
}

PermissionEntry is one row of the GET /<repo>/permissions response.

type PrincipalJSON 

type PrincipalJSON struct {
	ID        string `json:"id"`
	Username  string `json:"username"`
	PublicKey string `json:"public_key"`
}

PrincipalJSON is one entry in the GET /<repo>/principals roster response.

type PushFile 

type PushFile struct {
	Path            string `json:"path"`
	ChangeType      string `json:"change_type"`
	ObjectHash      string `json:"object_hash,omitempty"`
	Size            int64  `json:"size,omitempty"`
	BasedOnCommitID string `json:"based_on_commit_id,omitempty"`
}

PushFile is one file entry in a PushRequest.

type PushRequest 

type PushRequest struct {
	Message   string     `json:"message"`
	CreatedAt int64      `json:"created_at"`
	Parents   []string   `json:"parents"`
	Files     []PushFile `json:"files"`
}

PushRequest is the body of POST /<repo>/commits.

type PushResponse 

type PushResponse struct {
	ID  string `json:"id"`
	Seq int64  `json:"seq"`
}

PushResponse is the body of a successful 200 response to a push.

type RegisterRequest 

type RegisterRequest struct {
	Username  string `json:"username"`
	PublicKey string `json:"public_key"`
}

RegisterRequest is the body of POST /register (the open endpoint).

type RegisterResponse 

type RegisterResponse struct {
	PrincipalID string `json:"principal_id"`
}

RegisterResponse returns the server-assigned principal_id.

type RekeyRequest 

type RekeyRequest struct {
	PublicKey string `json:"public_key"`
}

RekeyRequest is the body of POST /rekey.

type RevokeRequest 

type RevokeRequest struct {
	Principal string `json:"principal"`
	Path      string `json:"path"`
}

RevokeRequest is the body of DELETE /<repo>/grants.

type Server 

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

Server is the AgentStore HTTP server.

func New 

func New(dataDir string) (*Server, error)

New creates a Server rooted at dataDir, loading config from server.toml if present.

func (*Server) Handler 

func (srv *Server) Handler() http.Handler

Handler returns an http.Handler suitable for use with httptest.NewServer.

func (*Server) Serve 

func (srv *Server) Serve(ln net.Listener) error

Serve serves on an already-bound listener, blocking until the server is shut down. Start binds the listener for callers; tests bind their own so they can learn the chosen port (e.g. an ephemeral "0.0.0.0:0").

func (*Server) Shutdown 

func (srv *Server) Shutdown(ctx context.Context) error

Shutdown gracefully drains the server.

func (*Server) Start 

func (srv *Server) Start(addr string) error

Start binds to addr and serves, blocking until the server is shut down. addr overrides server.toml if non-empty.

type WhoAmIResponse 

type WhoAmIResponse struct {
	PrincipalID string `json:"principal_id"`
	Username    string `json:"username"`
}

WhoAmIResponse is the body of GET /whoami.

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.