webserver

package
v0.3.4 Latest Latest
Warning

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

 Go to latest Published: Jun 5, 2026 License: MIT Imports: 58 Imported by: 0

Documentation

Overview

Package webserver provides the embedded HTTP server for honey.

Package webserver provides the embedded HTTP server for honey.

@title Honey Web API @version 1.0 @description REST API for the honey web UI (`honey web`). Authenticate with the same token printed at startup, or `HONEY_WEB_TOKEN`. WebSocket endpoints `GET /ws/ssh` and `GET /ws/pve-qemu-vnc` are not described by this OpenAPI document.

@contact.name honey

@host 127.0.0.1:8765 @BasePath / @schemes http

@securityDefinitions.apikey BearerAuth @in header @name Authorization @description Use `Authorization: Bearer <token>` where `<token>` is the web UI token.

@securityDefinitions.apikey HoneyTokenHeader @in header @name X-Honey-Token @description Alternative header: `X-Honey-Token: <token>`.

@securityDefinitions.apikey TokenQuery @in query @name token @description Optional query token (same value) for URLs: `?token=<token>`.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AuthToken 

func AuthToken() (string, error)

AuthToken returns a fixed token from the environment when set, or generates a random hex token.

Types

type ActiveTunnel added in v0.2.9 

type ActiveTunnel struct {
	ID        string    `json:"id"`
	Host      string    `json:"host"`
	RecordKey string    `json:"record_key"`
	Mapping   string    `json:"mapping"`
	StartedAt time.Time `json:"started_at"`
	Error     string    `json:"error,omitempty"`
	// contains filtered or unexported fields
}

ActiveTunnel is one in-process SSH port-forward tunnel.

type ConfigBackendEntryBody added in v0.2.9 

type ConfigBackendEntryBody map[string]interface{}

ConfigBackendEntryBody is one backends.{kind}[] element; shape depends on path param kind.

type ConfigSchemaResponse added in v0.2.9 

type ConfigSchemaResponse struct {
	JSONSchema map[string]interface{} `json:"json_schema"`
	UISchema   any                    `json:"ui_schema"`
}

ConfigSchemaResponse is returned by GET /api/v1/config/schema.

type CueExecDryRunResponse added in v0.2.9 

type CueExecDryRunResponse struct {
	Plan string `json:"plan"`
}

CueExecDryRunResponse is the JSON body when cue-exec runs in dry-run mode.

type CueExecExecuteResponse added in v0.2.9 

type CueExecExecuteResponse struct {
	Results []ui.HostExecResult `json:"results"`
}

CueExecExecuteResponse is the JSON body when cue-exec runs with execute true.

type CueExecRequest added in v0.2.9 

type CueExecRequest struct {
	RecipePath    string                 `json:"recipe_path,omitempty"`
	RecipeContent map[string]interface{} `json:"recipe_content,omitempty"`
	Execute       bool                   `json:"execute"`
	SSHUser       string                 `json:"ssh_user"`
	Records       []hosts.Record         `json:"records"`
	Env           []string               `json:"env,omitempty"`
	RecordSession bool                   `json:"record_session"`
}

CueExecRequest is the JSON body for POST /api/v1/cue-exec.

type ExecRequest added in v0.2.9 

type ExecRequest struct {
	SSHUser               string         `json:"ssh_user"`
	Command               string         `json:"command"`
	ExecMode              string         `json:"exec_mode,omitempty"`
	ScriptInterpreter     string         `json:"script_interpreter,omitempty"`
	InterpreterArgsQuoted bool           `json:"interpreter_args_quoted,omitempty"`
	FileExtension         string         `json:"file_extension,omitempty"`
	RemoveTmpFile         *bool          `json:"remove_tmp_file,omitempty"`
	RunAs                 string         `json:"run_as,omitempty"`
	ScriptArgs            []string       `json:"script_args,omitempty"`
	Records               []hosts.Record `json:"records"`
	RecordSession         bool           `json:"record_session"`
}

ExecRequest is the JSON body for POST /api/v1/exec.

type ExecResponse added in v0.2.9 

type ExecResponse struct {
	Results []ui.HostExecResult `json:"results"`
}

ExecResponse is the JSON body for a successful exec run.

type FilesAgentTransferRequest added in v0.2.9 

type FilesAgentTransferRequest struct {
	SSHUser         string               `json:"ssh_user"`
	AgentLocalPath  string               `json:"agent_local_path,omitempty"`
	AgentRemoteDir  string               `json:"agent_remote_dir,omitempty"`
	SourceRecord    hosts.Record         `json:"source_record"`
	SourcePath      string               `json:"source_path"`
	DestRecord      hosts.Record         `json:"dest_record"`
	DestPath        string               `json:"dest_path"`
	Cloud           ui.AgentCloudBackend `json:"cloud"`
	CloudBackendRef *ui.CloudBackendRef  `json:"cloud_backend_ref,omitempty"`
	Credentials     map[string]string    `json:"credentials"`
	KeepObject      bool                 `json:"keep_object,omitempty"`
	MaxRetries      int                  `json:"max_retries,omitempty"`
}

FilesAgentTransferRequest is the JSON body for agent-mediated file transfer.

type FilesAgentTransferResponse added in v0.2.9 

type FilesAgentTransferResponse struct {
	Events []ui.AgentTransferEvent `json:"events"`
}

FilesAgentTransferResponse is the JSON body for agent transfer results.

type FilesCopyRequest added in v0.2.9 

type FilesCopyRequest struct {
	Direction  string       `json:"direction"`
	SSHUser    string       `json:"ssh_user"`
	Record     hosts.Record `json:"record"`
	LocalPath  string       `json:"local_path"`
	RemotePath string       `json:"remote_path"`
}

FilesCopyRequest is the JSON body for copy between local and remote paths.

type FilesCopyResponse added in v0.2.9 

type FilesCopyResponse struct {
	Status string `json:"status"`
	Local  string `json:"local"`
	Remote string `json:"remote"`
}

FilesCopyResponse is returned by POST /api/v1/files/copy.

type FilesLocalListRequest added in v0.2.9 

type FilesLocalListRequest struct {
	Path string `json:"path"`
}

FilesLocalListRequest is the JSON body for listing local files.

type FilesLocalListResponse added in v0.2.9 

type FilesLocalListResponse struct {
	Root    string              `json:"root"`
	Path    string              `json:"path"`
	Entries []ui.LocalFileEntry `json:"entries"`
}

FilesLocalListResponse is the JSON body for local list results.

type FilesRemoteListRequest added in v0.2.9 

type FilesRemoteListRequest struct {
	SSHUser string       `json:"ssh_user"`
	Record  hosts.Record `json:"record"`
	Path    string       `json:"path"`
}

FilesRemoteListRequest is the JSON body for listing remote files over SSH.

type FilesRemoteListResponse added in v0.2.9 

type FilesRemoteListResponse struct {
	Path    string               `json:"path"`
	Entries []ui.RemoteFileEntry `json:"entries"`
}

FilesRemoteListResponse is the JSON body for remote list results.

type GraphPlanRequest added in v0.2.9 

type GraphPlanRequest struct {
	Path          string                 `json:"path,omitempty"`
	RecipeContent map[string]interface{} `json:"recipe_content,omitempty"`
}

GraphPlanRequest is the JSON body for POST /api/v1/recipes/graph-plan.

type HostPortsRequest added in v0.2.9 

type HostPortsRequest struct {
	SSHUser string       `json:"ssh_user"`
	Record  hosts.Record `json:"record"`
}

HostPortsRequest is the JSON body for POST /api/v1/host-ports.

type HostPortsResponse added in v0.2.9 

type HostPortsResponse struct {
	Ports []string `json:"ports"`
}

HostPortsResponse is returned by POST /api/v1/host-ports.

type LintDiagnostic added in v0.3.4 

type LintDiagnostic struct {
	Line     int    `json:"line"`
	Col      int    `json:"col"`
	Severity string `json:"severity"` // "error" | "warning"
	Message  string `json:"message"`
}

LintDiagnostic is one syntax/lint finding (1-based line/col).

type LintRequest added in v0.3.4 

type LintRequest struct {
	Language string `json:"language"` // "bash" or "python"
	Content  string `json:"content"`
}

LintRequest is the JSON body for POST /api/v1/lint.

type LintResponse added in v0.3.4 

type LintResponse struct {
	Available   bool             `json:"available"`
	Tool        string           `json:"tool,omitempty"`
	Diagnostics []LintDiagnostic `json:"diagnostics"`
}

LintResponse is the JSON body for a lint result. Available is false when no checker tool is installed on the server host (the UI then just highlights).

type MetaResponse added in v0.2.9 

type MetaResponse struct {
	Version                   string `json:"version"`
	Commit                    string `json:"commit"`
	Date                      string `json:"date"`
	ConfigPath                string `json:"config_path"`
	SessionRecordingAvailable bool   `json:"session_recording_available"`
	SessionRecordingRetention string `json:"session_recording_retention,omitempty"`
	SessionRecordingLastPurge string `json:"session_recording_last_purge_at,omitempty"`
	TerminalAssistAvailable   bool   `json:"terminal_assist_available"`
	LogsCommandAllowed        bool   `json:"logs_command_allowed"`
	MetricsURL                string `json:"metrics_url,omitempty"`
}

MetaResponse is returned by GET /api/v1/meta.

type Options 

type Options struct {
	ListenAddr         string // e.g. 127.0.0.1:8765
	Token              string
	ConfigPath         string // optional explicit --config
	Config             *config.File
	ExecRegistry       hostexec.Registry
	SearchRegistry     *searchrun.Registry
	RecordDir          string // optional session recording output dir
	LocalFilesRoot     string // optional root for local file browser/upload/download
	AgentBinaryPath    string // optional explicit honey-transfer-agent binary path
	AgentBuildCacheDir string // optional cache dir for auto-built agent binary
	Version            string
	Commit             string
	Date               string
	MaxUploadSize      int64 // default 100 << 20
	MetricsListenAddr  string
	Metrics            *metrics.Registry
	NoCache            bool
	Refresh            bool
	AllowLogsCommand   bool
	OnReady            func() // called after the listener is bound, before serving
}

Options configures the embedded web server.

type ProvidersResponse added in v0.2.9 

type ProvidersResponse struct {
	Providers []string `json:"providers"`
}

ProvidersResponse is returned by GET /api/v1/providers.

type PveQemuVncOfferRequest added in v0.2.9 

type PveQemuVncOfferRequest struct {
	Record hosts.Record `json:"record"`
}

PveQemuVncOfferRequest is the JSON body for POST /api/v1/pve-qemu-vnc-offer.

type PveQemuVncOfferResponse added in v0.2.9 

type PveQemuVncOfferResponse struct {
	SessionID   string `json:"session_id"`
	VNCPassword string `json:"vnc_password"`
}

PveQemuVncOfferResponse is returned on success.

type RecentRunEntry added in v0.2.9 

type RecentRunEntry struct {
	RecipeName        string         `json:"recipe_name"`
	RecipePath        string         `json:"recipe_path"`
	HostCount         int            `json:"host_count"`
	StartedAt         string         `json:"started_at"`
	RecordingID       string         `json:"recording_id"`
	RecipeContentHash string         `json:"recipe_content_hash,omitempty"`
	Edited            bool           `json:"edited"`
	Hosts             []hosts.Record `json:"hosts,omitempty"`
}

RecentRunEntry is one recent recipe run.

type RecentRunsResponse added in v0.2.9 

type RecentRunsResponse struct {
	Runs []RecentRunEntry `json:"runs"`
}

RecentRunsResponse is returned by GET /api/v1/recipes/recent-runs.

type RecipeListEntry added in v0.2.9 

type RecipeListEntry struct {
	Name string `json:"name"`
	Path string `json:"path"`
}

RecipeListEntry is one recipe in the list API response.

type RecipeViewRequest added in v0.2.9 

type RecipeViewRequest struct {
	Path string `json:"path"`
}

RecipeViewRequest is the JSON body for POST /api/v1/recipes/view.

type RecipeViewResponse added in v0.2.9 

type RecipeViewResponse struct {
	Content string `json:"content"`
}

RecipeViewResponse is the JSON body for a successful recipe view.

type RecipesAssistRequest added in v0.2.9 

type RecipesAssistRequest struct {
	RecipePath string         `json:"recipe_path"`
	Model      string         `json:"model"`
	UserPrompt string         `json:"user_prompt"`
	SSHUser    string         `json:"ssh_user"`
	Records    []hosts.Record `json:"records"`
}

RecipesAssistRequest is the JSON body for POST /api/v1/recipes/assist.

type RecipesAssistResponse added in v0.2.9 

type RecipesAssistResponse struct {
	Reply string `json:"reply"`
}

RecipesAssistResponse is the JSON body for a successful recipe assist reply.

type RecipesListResponse added in v0.2.9 

type RecipesListResponse struct {
	Recipes []RecipeListEntry `json:"recipes"`
}

RecipesListResponse is the JSON body for GET /api/v1/recipes.

type RecipesParseRequest added in v0.2.9 

type RecipesParseRequest struct {
	Path string `json:"path"`
}

RecipesParseRequest is the JSON body for POST /api/v1/recipes/parse.

type RecipesParseResponse added in v0.2.9 

type RecipesParseResponse struct {
	Recipe map[string]interface{} `json:"recipe"`
}

RecipesParseResponse is the JSON body for a successful recipe parse.

type RecordingListEntry added in v0.2.9 

type RecordingListEntry struct {
	FileName       string `json:"file_name"`
	ModifiedUnixMS int64  `json:"modified_unix_ms"`
	SizeBytes      int64  `json:"size_bytes"`
	Trigger        string `json:"trigger,omitempty"`
	Mode           string `json:"mode,omitempty"`
	Provider       string `json:"provider,omitempty"`
	HostName       string `json:"host_name,omitempty"`
	HostIP         string `json:"host_ip,omitempty"`
	User           string `json:"user,omitempty"`
}

RecordingListEntry is one session recording file in a list response.

type RecordingsListResponse added in v0.2.9 

type RecordingsListResponse struct {
	Items      []RecordingListEntry     `json:"items"`
	FileCount  int                      `json:"file_count"`
	TotalBytes int64                    `json:"total_bytes"`
	Retention  *RecordingsRetentionInfo `json:"retention,omitempty"`
}

RecordingsListResponse is returned by GET /api/v1/recordings.

type RecordingsPlayRequest added in v0.2.9 

type RecordingsPlayRequest struct {
	FileName string `json:"file_name"`
}

RecordingsPlayRequest is the JSON body for POST /api/v1/recordings/play.

type RecordingsPlayResponse added in v0.2.9 

type RecordingsPlayResponse struct {
	FileName string             `json:"file_name"`
	Events   []recordings.Event `json:"events"`
}

RecordingsPlayResponse is returned by POST /api/v1/recordings/play.

type RecordingsRetentionInfo added in v0.3.0 

type RecordingsRetentionInfo struct {
	Enabled bool   `json:"enabled"`
	MaxAge  string `json:"max_age,omitempty"`
}

RecordingsRetentionInfo describes auto-TTL policy for the record dir.

type RecordingsSummarizeRequest added in v0.3.0 

type RecordingsSummarizeRequest struct {
	FileName string `json:"file_name"`
	Model    string `json:"model"`
}

RecordingsSummarizeRequest is the JSON body for POST /api/v1/recordings/summarize.

type RecordingsSummarizeResponse added in v0.3.0 

type RecordingsSummarizeResponse struct {
	Reply string `json:"reply"`
}

RecordingsSummarizeResponse is returned by POST /api/v1/recordings/summarize.

type ResolvedStepSummary added in v0.2.8 

type ResolvedStepSummary struct {
	Index   int      `json:"index"`
	ID      string   `json:"id,omitempty"`
	Depends []string `json:"depends,omitempty"`
	Wave    int      `json:"wave,omitempty"`
	Kind    string   `json:"kind"`
	Host    string   `json:"host"`
	RunAs   string   `json:"run_as,omitempty"`
	When    string   `json:"when,omitempty"`
	Retry   string   `json:"retry,omitempty"`
	Notify  bool     `json:"notify,omitempty"`
	Preview string   `json:"preview"`
}

ResolvedStepSummary is the per-step shape returned to the WebUI's Plan view. It mirrors cuetry.StepSummary; keep it small and JSON-stable — the wizard renders it directly.

type Server 

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

Server is the honey web UI HTTP server.

func NewServer 

func NewServer(opts Options) (*Server, error)

NewServer builds handlers with the given auth token.

func (*Server) Start 

func (s *Server) Start(ctx context.Context) error

Start listens and serves until ctx is cancelled.

type StartTunnelRequest added in v0.2.9 

type StartTunnelRequest struct {
	SSHUser string       `json:"ssh_user"`
	Record  hosts.Record `json:"record"`
	Mapping string       `json:"mapping"`
}

StartTunnelRequest is the JSON body for POST /api/v1/tunnels.

type StatusResponse added in v0.2.9 

type StatusResponse struct {
	Status string `json:"status"`
	Path   string `json:"path"`
}

StatusResponse is returned by config write endpoints.

type TerminalAssistModelsResponse added in v0.2.9 

type TerminalAssistModelsResponse struct {
	Models []string `json:"models"`
}

TerminalAssistModelsResponse is returned by GET /api/v1/terminal-assist/models.

type TerminalAssistRequest added in v0.2.9 

type TerminalAssistRequest struct {
	UserPrompt string `json:"user_prompt"`
	Scrollback string `json:"scrollback"`
	MaxLines   int    `json:"max_lines"`
	Model      string `json:"model"`
}

TerminalAssistRequest is the JSON body for POST /api/v1/terminal-assist.

type TerminalAssistResponse added in v0.2.9 

type TerminalAssistResponse struct {
	Reply             string `json:"reply"`
	ScrollbackClipped bool   `json:"scrollback_clipped"`
}

TerminalAssistResponse is returned by POST /api/v1/terminal-assist.

type TunnelDeleteResponse added in v0.2.9 

type TunnelDeleteResponse struct {
	Success bool `json:"success"`
}

TunnelDeleteResponse is returned by DELETE /api/v1/tunnels/{id}.

type TunnelLogsResponse added in v0.2.9 

type TunnelLogsResponse struct {
	Logs string `json:"logs"`
}

TunnelLogsResponse is returned by GET /api/v1/tunnels/{id}/logs.

type TunnelStartResponse added in v0.2.9 

type TunnelStartResponse struct {
	Tunnel ActiveTunnel `json:"tunnel"`
}

TunnelStartResponse is returned by POST /api/v1/tunnels.

type TunnelsListResponse added in v0.2.9 

type TunnelsListResponse struct {
	Tunnels []ActiveTunnel `json:"tunnels"`
}

TunnelsListResponse is returned by GET /api/v1/tunnels.

type UploadRequestMeta added in v0.2.9 

type UploadRequestMeta struct {
	SSHUser    string       `json:"ssh_user"`
	RemotePath string       `json:"remote_path"`
	Record     hosts.Record `json:"record"`
}

UploadRequestMeta is the JSON in multipart field "meta" for POST /api/v1/upload.

type UploadResponse added in v0.2.9 

type UploadResponse struct {
	Results []ui.HostExecResult `json:"results"`
}

UploadResponse is the non-stream JSON body for POST /api/v1/upload.

type ValidateContentError added in v0.2.9 

type ValidateContentError struct {
	Path    string `json:"path,omitempty"`
	Kind    string `json:"kind"`
	Message string `json:"message"`
}

ValidateContentError is one validation issue.

type ValidateContentRequest added in v0.2.9 

type ValidateContentRequest struct {
	RecipeContent map[string]interface{} `json:"recipe_content"`
}

ValidateContentRequest is the JSON body for POST /api/v1/recipes/validate-content.

type ValidateContentResponse added in v0.2.9 

type ValidateContentResponse struct {
	Plan   string                  `json:"plan,omitempty"`
	Steps  []ResolvedStepSummary   `json:"steps,omitempty"`
	Graph  *cuetry.RecipeGraphPlan `json:"graph,omitempty"`
	Errors []ValidateContentError  `json:"errors,omitempty"`
}

ValidateContentResponse is returned on success or validation failure.

type WSHello added in v0.2.9 

type WSHello struct {
	SessionID     string       `json:"session_id"`
	SSHUser       string       `json:"ssh_user"`
	Record        hosts.Record `json:"record"`
	Cols          int          `json:"cols"`
	Rows          int          `json:"rows"`
	RecordSession bool         `json:"record_session"`
	Console       string       `json:"console,omitempty"` // "truenas_api" for TrueNAS /websocket/shell
}

WSHello is exported so it can be unmarshaled by the honey pty-proxy subcommand.

Source Files

View all Source files

Directories

Path Synopsis
cmd
swag2openapi command
Command swag2openapi converts swag-generated Swagger 2.0 JSON to OpenAPI 3.x JSON for honey web.
 Command swag2openapi converts swag-generated Swagger 2.0 JSON to OpenAPI 3.x JSON for honey web.

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.