api

package
v0.0.0-nightly.20260811 Latest Latest
Warning

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

Go to latest
Published: Aug 10, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

Documentation

Overview

Package api implements AIScan's protocol-neutral Web management API.

Methods consume and return generated protobuf messages. Transport packages only adapt envelopes and error codes; Agent execution remains delegated to the existing AOP/AgentPool runtime.

Index

Constants

View Source
const (
	SessionStateOpen   = "open"
	SessionStateClosed = "closed"
)
View Source
const DefaultReportLang = "zh"

Variables

View Source
var (
	ErrScanNotFound      = errors.New("scan not found")
	ErrScanNotCancelable = errors.New("scan cannot be canceled")
)
View Source
var ErrTurnNotFound = errors.New("turn not found")

Functions

func BeginRequest

func BeginRequest(ctx context.Context, store RequestJournal, method, requestID string, request, response proto.Message) ([]byte, bool, bool, error)

func BuildMarkdownReport

func BuildMarkdownReport(target, mode string, rawNodes []json.RawMessage, lang string) string

func ConfigView

func ConfigView(config *types.DistributeConfig, path string, loaded bool) *types.ConfigView

func Errorf

func Errorf(code Code, format string, args ...any) error

func FinishRequest

func FinishRequest(ctx context.Context, store RequestJournal, method, requestID string, hash []byte, response proto.Message) error

func NewError

func NewError(code Code, err error) error

func ScanCompletedEvent

func ScanCompletedEvent(scanID string) *types.ScanEvent

func ScanFailedEvent

func ScanFailedEvent(scanID, message string, canceled bool) *types.ScanEvent

func ScanProgressEvent

func ScanProgressEvent(scanID, data string) *types.ScanEvent

func ScanSnapshot

func ScanSnapshot(scan *types.Scan, sequence uint64) *types.ScanEvent

func ScanStatusEvent

func ScanStatusEvent(scanID string, status types.ScanStatus) *types.ScanEvent

func ScanTerminal

func ScanTerminal(status types.ScanStatus) bool

func ServeApplication

func ServeApplication(connection ApplicationConnection, first *aop.Envelope, backends *ApplicationBackends) error

ServeApplication serves one application connection over the AOP envelope surface. Connection owns stream concurrency; this function owns only the application business routes and connection-local subscriptions.

func ValidateLLMConfig

func ValidateLLMConfig(config *types.LLMConfig) error

Types

type API

type API struct {
	Sessions  *Sessions
	Config    *Config
	Scans     *Scans
	SCO       *SCO
	Agents    AgentReader
	Status    StatusReader
	ServerURL string
}

func (*API) GetStatus

func (*API) ListAgents

type AgentReader

type AgentReader interface {
	List() []*types.AgentView
	Count() int
}

type ApplicationBackends

type ApplicationBackends struct {
	Sessions *Sessions
	Scans    *Scans
	Commands CommandExecutor
	Files    FileUploader
	PTY      PTYRouter
	NewID    func() string
}

ApplicationBackends wires the application envelope business surface to its owning mechanisms.

type ApplicationConnection

type ApplicationConnection interface {
	Context() context.Context
	Send(*aop.Envelope) error
	Run(*aop.Envelope, func(context.Context, *aop.Envelope, aop.SendFunc) error) error
}

ApplicationConnection is the minimal mechanism surface required by the application business dispatcher. pkg/web owns the concrete Connection.

type ArtifactNormalizer

type ArtifactNormalizer interface {
	NormalizeArtifact(context.Context, string, string, []byte) (uint64, uint64, error)
	SupportedArtifacts() []string
}

type Code

type Code string
const (
	CodeInvalidArgument    Code = "INVALID_ARGUMENT"
	CodeNotFound           Code = "NOT_FOUND"
	CodeAlreadyExists      Code = "ALREADY_EXISTS"
	CodeFailedPrecondition Code = "FAILED_PRECONDITION"
	CodeResourceExhausted  Code = "RESOURCE_EXHAUSTED"
	CodeUnavailable        Code = "UNAVAILABLE"
	CodeInternal           Code = "INTERNAL"
)

func ErrorCode

func ErrorCode(err error) Code

type CommandExecutor

type CommandExecutor interface {
	ExecuteSessionCommand(sessionID, line string) (string, error)
}

CommandExecutor runs "/" commands inside a chat session.

type Config

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

func NewConfig

func NewConfig(options ConfigOptions) *Config

func (*Config) Activate

func (c *Config) Activate(ctx context.Context, id string) (*types.ConfigView, error)

func (*Config) ActivateProfile

func (c *Config) ActivateProfile(ctx context.Context, request *types.ActivateProfileRequest) (*types.ActivateProfileResponse, error)

func (*Config) Distribute

func (c *Config) Distribute(ctx context.Context) (*types.DistributeConfig, error)

func (*Config) GetConfig

func (*Config) ListModels

func (c *Config) ListModels(ctx context.Context, request *types.LLMProbeRequest) (*types.ListModelsResult, error)

func (*Config) Save

func (c *Config) Save(ctx context.Context, config *types.DistributeConfig) (*types.ConfigView, error)

func (*Config) TestConnection

func (c *Config) TestConnection(ctx context.Context, request *types.TestConnectionRequest) (*types.TestConnectionResponse, error)

func (*Config) TestLLM

func (c *Config) TestLLM(ctx context.Context, request *types.LLMProbeRequest) (*types.LLMProbeResult, error)

func (*Config) UpdateConfig

func (c *Config) UpdateConfig(ctx context.Context, request *types.UpdateConfigRequest) (*types.UpdateConfigResponse, error)

func (*Config) View

func (c *Config) View(ctx context.Context) (*types.ConfigView, error)

type ConfigOptions

type ConfigOptions struct {
	Store     ConfigStore
	Build     func(context.Context, *PreparedConfig) (*runner.App, error)
	Apply     func(*runner.App)
	Broadcast func(*types.DistributeConfig)
}

type ConfigStore

type ConfigStore interface {
	GetDistributeConfig(context.Context) (string, bool, *types.DistributeConfig, error)
	PrepareDistributeConfig(context.Context, *types.DistributeConfig) (*PreparedConfig, error)
	CommitDistributeConfig(context.Context, *PreparedConfig) error
	DiscardDistributeConfig(*PreparedConfig)
}

type Error

type Error struct {
	Code Code
	Err  error
}

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type FileUploader

type FileUploader interface {
	Upload(ctx context.Context, sessionID, filename string, data []byte) (*filepb.Result, error)
}

FileUploader stores an application-uploaded file through the owning agent.

type PTYRouter

type PTYRouter interface {
	SubscribePTY(nodeID, streamID string) (<-chan *ptypb.ProtocolMessage, bool, func())
	ForwardPTY(nodeID string, message *ptypb.ProtocolMessage) error
	ClosePTY(nodeID, streamID string)
}

PTYRouter bridges application PTY messages to the agent owning the terminal. It speaks generated protobuf only; frame conversion belongs to the mechanism layer implementing this interface.

type PreparedConfig

type PreparedConfig struct {
	Config      *types.DistributeConfig
	RuntimePath string
	TargetPath  string
}

type RequestJournal

type RequestJournal interface {
	LoadAOPRequest(context.Context, string, string, []byte, proto.Message) (bool, bool, error)
	SaveAOPRequest(context.Context, string, string, []byte, proto.Message) error
}

type SCO

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

func NewSCO

func NewSCO(store SCOStore, normalizers ...ArtifactNormalizer) *SCO

func (*SCO) DeleteNodes

func (s *SCO) DeleteNodes(ctx context.Context, request *types.DeleteNodesRequest) (*types.DeleteNodesResponse, error)

func (*SCO) GetNode

func (s *SCO) GetNode(ctx context.Context, request *types.GetNodeRequest) (*types.GetNodeResponse, error)

func (*SCO) GetStats

func (*SCO) ImportNodes

func (s *SCO) ImportNodes(ctx context.Context, request *types.ImportNodesRequest) (*types.ImportNodesResponse, error)

func (*SCO) ListNodes

func (s *SCO) ListNodes(ctx context.Context, request *types.ListNodesRequest) (*types.ListNodesResponse, error)

type SCOStore

type SCOStore interface {
	ListSCONodesByScanID(context.Context, string, string, int) ([]json.RawMessage, error)
	GetSCONode(context.Context, string) (json.RawMessage, error)
	SCONodeStats(context.Context) (map[string]int, error)
	DeleteSCONodesByScan(context.Context, string) error
	UpsertSCONodes(context.Context, string, []json.RawMessage) error
}

type ScanBackend

type ScanBackend interface {
	SubmitScan(context.Context, string, string, bool, bool, bool) (*types.Scan, error)
	GetScan(context.Context, string) (*types.Scan, error)
	ListScans(context.Context) ([]*types.Scan, error)
	CancelScan(string) error
	GetReport(context.Context, string, string) (string, error)
}

type ScanEvents

type ScanEvents interface {
	SubscribeScan(string) (<-chan *types.ScanEvent, uint64, func())
}

type Scans

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

func NewScans

func NewScans(backend ScanBackend, events ScanEvents) *Scans

func (*Scans) CancelScan

func (s *Scans) CancelScan(ctx context.Context, request *types.CancelScanRequest) (*types.CancelScanResponse, error)

func (*Scans) GetScan

func (s *Scans) GetScan(ctx context.Context, request *types.GetScanRequest) (*types.GetScanResponse, error)

func (*Scans) GetScanReport

func (s *Scans) GetScanReport(ctx context.Context, request *types.GetScanReportRequest) (*types.GetScanReportResponse, error)

func (*Scans) ListScans

func (*Scans) SubmitScan

func (s *Scans) SubmitScan(ctx context.Context, request *types.SubmitScanRequest) (*types.SubmitScanResponse, error)

func (*Scans) WatchScanEvents

func (s *Scans) WatchScanEvents(request *types.WatchScanEventsRequest, ctx context.Context, send func(*types.ScanEvent) error) error

type SessionRuntime

type SessionRuntime interface {
	AgentInfo(string) (string, bool)
	GetScan(context.Context, string) (*types.Scan, error)
	OpenAgentSession(context.Context, string, *aop.OpenSessionRequest) error
	CloseAgentSession(context.Context, string, string, *aop.CloseSessionRequest) (bool, error)
	StartAgentTurn(string, *aop.RunTurnRequest)
	CancelTurn(context.Context, string, string) error
	PublishUserMessage(string, string, *aop.Message)
	BroadcastAOPEvent(string, *aop.Event)
	SubscribeSessionEvents(string) (<-chan *aop.EventDelivery, func())
	DeleteSession(context.Context, string) error
	SessionMenu(string) []*types.CommandSpec
}

SessionRuntime is the Agent/AOP execution boundary. Sessions owns request semantics and persistence; the runtime only performs Agent dispatch and live event delivery.

type SessionStore

type SessionStore interface {
	RequestJournal
	ListSessionPage(context.Context, int, int, bool) ([]*types.SessionRecord, bool, error)
	GetSession(context.Context, string) (*types.SessionRecord, error)
	CreateSession(context.Context, *types.SessionRecord) error
	UpdateSession(context.Context, *types.SessionRecord) error
	DeleteSession(context.Context, string) error
	LinkScanToSession(context.Context, string, string) error
	ListAOPEventsAfter(context.Context, string, int64, int) ([]*aop.EventDelivery, error)
}

type Sessions

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

func NewSessions

func NewSessions(store SessionStore, runtime SessionRuntime, newID func() string) *Sessions

func (*Sessions) CancelTurn

func (s *Sessions) CancelTurn(ctx context.Context, requestID string, request *aop.CancelTurnRequest) (*aop.CancelTurnResponse, error)

func (*Sessions) CloseSession

func (s *Sessions) CloseSession(ctx context.Context, requestID string, request *aop.CloseSessionRequest) (*aop.CloseSessionResponse, error)

func (*Sessions) DeleteSession

func (s *Sessions) DeleteSession(ctx context.Context, request *types.DeleteSessionRequest) (*types.DeleteSessionResponse, error)

func (*Sessions) GetSession

func (s *Sessions) GetSession(ctx context.Context, request *types.GetSessionRequest) (*types.GetSessionResponse, error)

func (*Sessions) ListCommands

func (*Sessions) ListEvents

func (s *Sessions) ListEvents(ctx context.Context, request *aop.ListEventsRequest) (*aop.ListEventsResponse, error)

func (*Sessions) ListSessions

func (s *Sessions) ListSessions(ctx context.Context, request *types.ListSessionsRequest) (*types.ListSessionsResponse, error)

func (*Sessions) OpenSession

func (s *Sessions) OpenSession(ctx context.Context, requestID string, request *aop.OpenSessionRequest) (*aop.OpenSessionResponse, error)

func (*Sessions) ResetSession

func (s *Sessions) ResetSession(ctx context.Context, request *types.ResetSessionRequest) (*types.ResetSessionResponse, error)

func (*Sessions) RunTurn

func (s *Sessions) RunTurn(ctx context.Context, requestID string, request *aop.RunTurnRequest) (*aop.RunTurnResponse, error)

func (*Sessions) WatchEvents

func (s *Sessions) WatchEvents(ctx context.Context, request *aop.WatchEventsRequest, send func(*aop.EventDelivery) error) error

type StatusReader

type StatusReader interface {
	Status() *types.SystemStatus
}

Jump to

Keyboard shortcuts

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