Documentation
¶
Overview ¶
Package sdk defines the contract for building GoScouter modules.
A module is a self-contained scouting capability: given a target, it gathers information and returns a renderable result. Developers implement Module and the GoScouter host application is responsible for discovering, loading, and running it.
A module is distributed as a standalone executable. The host discovers, downloads, and caches that binary, then loads it with Open, which returns a Binary that satisfies Module by invoking the executable as a subprocess.
A module binary must implement a small command-line protocol:
<binary> describe
Write a JSON [Descriptor] to stdout and exit 0.
<binary> scout -target <target> [module flags...]
Run against target, write the rendered result to stdout, and exit 0.
Any operator-supplied module flags are forwarded verbatim after
-target; the binary parses its own flags. On failure, write a message
to stderr and exit with a non-zero status.
Any executable that honors this protocol is a valid module, regardless of the language it is written in. The Module and Result interfaces describe the same contract in Go terms, and are the types the host works with once a binary is loaded.
Downloading, caching, verifying, and registering modules is the host's responsibility; the SDK owns the interfaces and the wire protocol they travel over.
Index ¶
Constants ¶
const ProtocolVersion = 3
ProtocolVersion is the version of the host<->module wire protocol implemented by this SDK. A module binary reports it in its Descriptor so the host can refuse binaries built against an incompatible protocol.
Variables ¶
This section is empty.
Functions ¶
func Serve ¶
Serve runs m as a module binary, speaking the stdio protocol on this process's stdin and stdout. It is the entire body a module author needs in main:
func main() {
if err := sdk.Serve(myModule{}); err != nil {
log.Fatal(err)
}
}
Serve reads one JSON request per line from stdin and writes one JSON response per line to stdout, dispatching each request in its own goroutine so a single process can service many targets concurrently. Because requests run concurrently, m must be safe for concurrent use, as Module requires. Serve returns when stdin reaches EOF, which the host triggers by closing the session.
Types ¶
type Binary ¶
type Binary struct {
// contains filtered or unexported fields
}
Binary is a handle to a running module binary. It implements Module by speaking the stdio protocol to a single long-lived subprocess: the process is spawned once by Open and reused for every Binary.Scout call until Binary.Close. This keeps a scan of many targets to one subprocess per module instead of one per target.
Downloading, verifying, and caching the binary on disk is the host's responsibility; Binary only manages the process and the protocol once the executable is present at path. A Binary is safe for concurrent use: Scout may be called from many goroutines at once.
func Open ¶
Open spawns the module binary at path and completes a describe handshake. It starts the process, reads the module's Descriptor, and rejects binaries built against an incompatible ProtocolVersion. The process stays running until Binary.Close; callers must Close every Binary they Open.
func (*Binary) Close ¶
Close shuts the session down: it signals the module to exit by closing its stdin, waits for the read loop to drain, and reaps the process. It is safe to call more than once.
func (*Binary) Description ¶
type Descriptor ¶
type Descriptor struct {
// Protocol is the wire-protocol version the binary was built against.
Protocol int `json:"protocol"`
// Name is the unique identifier the module is invoked by.
Name string `json:"name"`
// Description is a one-line human-readable summary.
Description string `json:"description"`
// Version is the module's own version.
Version string `json:"version"`
}
Descriptor is the metadata a module reports in response to a describe request. It is the JSON contract a module writes and Open reads during the handshake.
type Module ¶
type Module interface {
// Name is the unique identifier the module is invoked by. It must be
// stable, lower-case, and contain no spaces.
Name() string
// Description is a one-line human-readable summary shown in help output.
Description() string
// Version is the module's own version, independent of the SDK version.
// Semantic versioning (e.g. "1.2.0") is recommended.
Version() string
// Scout gathers information about target and returns a renderable result.
// target is the raw string supplied by the operator (typically a URL).
// args carries any module-specific flags the operator passed after the
// module name (e.g. []string{"--https"}); modules that take no options
// ignore it.
Scout(target string, args []string) (Result, error)
}
Module is a scouting capability that GoScouter can run against a target.
Implementations must be safe to call concurrently: the host may invoke Scout on the same Module value from multiple goroutines.
type Result ¶
type Result interface {
// Render returns the result formatted for display in the GoScouter
// terminal. Use "\r\n" line endings, as the host runs in raw mode.
Render() string
}
Result is the outcome of a Module.Scout call. It knows how to present itself as terminal-ready text.
Source Files