webserver

package
v0.3.5 Latest Latest
Warning

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

 Go to latest Published: Jun 13, 2026 License: MIT Imports: 61 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.

func ResolveToken added in v0.3.5 

func ResolveToken(stateDir string) (string, error)

ResolveToken returns a stable web auth token. Precedence:

  1. HONEY_WEB_TOKEN env var, if set;
  2. a token previously persisted at stateDir/web_token;
  3. a freshly generated token, which is then persisted to stateDir/web_token.

Persisting the generated token keeps it stable across restarts (e.g. a docker container with a mounted state volume) so a bookmarked ?token= URL keeps working. A persist failure is non-fatal: the generated (ephemeral) token is still returned.

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
	DisableAuth        bool   // when true, skip token auth entirely (trusted networks / authenticating proxy)
	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 StoreLoadResponse added in v0.3.5 

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

StoreLoadResponse is returned by GET /api/v1/recipes/store/{name}. It combines the parsed recipe with graph/plan data so the Studio needs only one call.

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.
Package recipestore provides extensible storage abstractions for managing recipe content.
 Package recipestore provides extensible storage abstractions for managing recipe content.

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.