expect

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Nov 5, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

README

go-expect

Go 1.26+ conversations with interactive programs and duplex streams: bounded matching, continuations, reusable rules, process terminals and streaming secret redaction. Import github.com/gatework/go-expect.

NewSession takes exclusive ownership of an io.ReadWriteCloser only on success. Its Close must interrupt concurrent reads and writes. Register secrets with Redact before sending or receiving them; matching results retain raw bytes.

The example below is copied from example_test.go, compiled and executed by go test. script/readme.py checks that the copy stays synchronized.

// SPDX-License-Identifier: Apache-2.0

package expect_test

import (
	"context"
	"fmt"
	"io"
	"net"

	expect "github.com/gatework/go-expect"
)

func ExampleSession_Expect() {
	local, remote := net.Pipe()
	session, err := expect.NewSession(local, expect.WithLineEnding("\r"))
	if err != nil {
		panic(err)
	}
	defer session.Close()
	done := make(chan struct{})
	go func() {
		defer close(done)
		defer remote.Close()
		_, _ = remote.Write([]byte("Password:"))
		b := make([]byte, 7)
		_, _ = io.ReadFull(remote, b)
		_, _ = remote.Write([]byte("router#"))
	}()
	if err = session.Redact("secret"); err != nil {
		panic(err)
	}
	result, err := session.Expect(context.Background(), []expect.Case{
		{Pattern: expect.Literal("Password:"), Handler: expect.ReplyThenContinue("secret\r"), Limit: 1},
		{Pattern: expect.Line("router#")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(result.CaseIndex, result.Match)
	<-done
	// Output: 1 router#
}

Run the longer password, confirmation and paging example with go run ./examples/dialogue. Device authentication, vendor profiles and backup policy belong to go-net-connector, not to the stream engine.

Task API and behavior
Match text Literal, Line, Compile, FromRegexp, Glob, All
Case folding Pattern.Fold; Unicode regexp folding, Go leftmost-first matching
Preview WithNoConsume; successful Return leaves input for the next wait
Inspect match Result.Buffer, Capture(name), Indices(group); half-open byte offsets
Repeat Continue resets the relative timer; ContinueKeepTimer preserves it; zero action is Return
Recover timeout Timeout, Default, FullBuffer cases with bounded Case.Limit
Reuse rules WithBefore, WithAfter, per-call WithRules; Session.Rules returns a copy
Reply ReplyThenContinue, or Then(Response) for dynamic replies
Send Send writes once; SendAll drains peer input while writing suffixes
Slow devices SendSlow, SendNull, transport-capability SendBreak
Trace safely WithLogger(*slog.Logger), WithObserver, WithTrace; metadata only
Record streams WithOutput and WithSendOutput; independent redacted streams
Take over Interact, local Literal sequence actions, remote pattern actions; InteractTerminal for Unix raw input
Watch several ExpectAny; only the winner consumes input and invokes handlers
Watch asynchronously StartBackground; Stop cancels and joins the wait
Normalize input Opt-in WithRemoveNulls(true), WithStripParity(true)

Before rules take precedence over call cases, then After rules. Within a group, the earliest visible byte wins; declaration order breaks ties. Per-call rules follow foreground cases, so completion wins an exact tie. WithMatchOrder(Declaration) selects the first declared matching case within its group. Limits count per wait; rule/event defaults are one invocation, and ordinary cases default to unlimited.

Timeout handles only the relative wait timer; parent cancellation and idle timeouts remain errors. Its callback receives a fresh relative budget, allowing it to send and Continue. Default handles relative timeout or clean EOF. FullBuffer explicitly consumes the full unmatched snapshot; without it overflow returns ErrBufferLimit and preserves data. No automatic trimming occurs.

Use a parent context to bound the whole dialogue. A matching prompt is not proof that a command succeeded. Sends are serialized, but callers must sequence commands and responses. Failures after write admission retire the session and return exact WriteError.Written progress; commands are never retried implicitly.

Interact owns its input reader after admission and closes it on exit. Output is borrowed and filtered. Control-] exits by default. Use WithInteractInputCases for byte-exact local Literal sequences and WithInteractOutputCases for remote patterns; callbacks run on the receive owner. InteractTerminal borrows an *os.File, duplicates it, enables raw mode and restores the original terminal state. Interaction retains a matching window of min(64 KiB, buffer limit), consuming half when unmatched (at least one byte), so patterns requiring arbitrary historical prefixes are unsuitable. Stop and interactive cleanup join cooperative callbacks; Session.Close does not wait for user code.

Process adapter Ownership and platform
Console.Start(*exec.Cmd) New session and controlling terminal; caller must cancel and Wait
spawn.Start(ctx, program, args, ...) Linux/macOS; owns child and PTY; group SIGHUP, two-second direct-child kill fallback
conpty.Start(ctx, program, args, ...) Windows 10 1809+; owns pseudoconsole and kill-on-close job

Unix PTYs default to 24 rows by 80 columns. WithSize, SetSize and SetEcho control dimensions/echo; WithRaw configures raw slave input. Console.Start closes the parent's slave after successful start. The Unix adapter also compiles for FreeBSD; runtime verification is pending. Windows ConPTY carries UTF-8/VT sequences; it does not expose POSIX echo or break controls. Consume process output before Wait, or call Close to interrupt an undrained process. Unix descendant processes must cooperate with SIGHUP.

Tcl expect convention This library
Declaration order Earliest byte by default; opt into Declaration
10-second timeout 30-second wait, 10-second Send
-1 means unlimited NoTimeout (zero); negatives are invalid
Unhandled timeout returns ErrTimeout
match_max may drop old data Bounded input; overflow preserves it
NUL removal by default Bytes preserved unless filtering is enabled
Tcl ARE expressions Go RE2; no backreferences or lookahead
Typical send terminator CR Send/Reply verbatim, SendLine defaults to LF

See contracts, migration, verification and release operations. The source retains Netflix's Apache-2.0 license and copyright notices.

Run bash script/ci for local checks. CI runs Linux/macOS Go 1.26/1.27 and Windows runtime tests. Default-branch pushes publish after all gates pass. Before v1, BREAKING: or BREAKING CHANGE: commit trailers select the next minor version; ordinary changes increment patch. No compatibility aliases are provided.

Documentation

Overview

Package expect automates interactive byte streams with bounded waits, continuation callbacks and reusable response rules. Session owns a supplied duplex transport; Console adapts Unix PTYs. The spawn and conpty subpackages own child process lifetimes. Callers own connections and command success checks.

Matching preserves input unless explicit normalization options are enabled. Diagnostics and output copies use explicit streaming secret redaction. Result fields are raw, detached snapshots.

Index

Examples

Constants

View Source 
const NoTimeout time.Duration = 0

NoTimeout disables a relative timeout; parent context deadlines still apply.

Variables

View Source 
var (
	ErrInvalidPattern  = errors.New("expect: invalid pattern")
	ErrClosed          = errors.New("expect: session closed")
	ErrBusy            = errors.New("expect: another expect operation is active")
	ErrTimeout         = errors.New("expect: timeout")
	ErrIdleTimeout     = errors.New("expect: idle timeout")
	ErrBufferLimit     = errors.New("expect: buffer limit reached")
	ErrEmptyMatch      = errors.New("expect: empty match")
	ErrPollUnsupported = errors.New("expect: OS polling unsupported")
)

Sentinel errors describe protocol and lifecycle failures.

View Source 
var ErrBreakUnsupported = errors.New("expect: transport break unsupported")

ErrBreakUnsupported indicates that the transport cannot assert a line break.

Functions

This section is empty.

Types

type Action 

type Action uint8

Action determines whether a matched Case returns or continues waiting. 

const (
	Return Action = iota
	Continue
	ContinueKeepTimer
)

Actions determine whether a handler returns or continues waiting.

type Background added in v0.2.0 

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

Background is an owned asynchronous wait. Continue actions keep watching; Return, EOF, cancellation or failure completes it. Stop cancels and joins it.

func (*Background) GoString added in v0.2.0 

func (p *Background) GoString() string

GoString formats the handle without exposing owned stream or command state.

func (*Background) Stop added in v0.2.0 

func (b *Background) Stop()

Stop cancels the wait without closing its transport and joins callbacks.

func (*Background) String added in v0.2.0 

func (*Background) String() string

String formats the handle without exposing owned stream or command state.

func (*Background) Wait added in v0.2.0 

func (b *Background) Wait() (Result, error)

Wait joins the background wait and returns its final snapshot.

type Capture 

type Capture struct {
	Text       string
	Matched    bool
	Name       string
	Start, End int
}

Capture distinguishes an unmatched optional group from an empty matched group.

func (Capture) GoString 

func (c Capture) GoString() string

GoString formats metadata without exposing payloads.

func (Capture) String 

func (Capture) String() string

type Case 

type Case struct {
	Pattern Pattern
	Handler Handler
	Limit   int
}

Case associates a pattern with an optional handler (nil means Return).

func (Case) GoString 

func (c Case) GoString() string

GoString formats metadata without exposing payloads.

func (Case) String 

func (Case) String() string

type CompileError added in v0.2.0 

type CompileError struct{ Code syntax.ErrorCode }

CompileError retains the syntax category, never the original expression.

func (*CompileError) Error added in v0.2.0 

func (e *CompileError) Error() string

func (*CompileError) Unwrap added in v0.3.0 

func (e *CompileError) Unwrap() error

Unwrap identifies a rejected pattern without revealing its expression.

type ConfigError added in v0.2.0 

type ConfigError struct {
	Option string
	Reason string
}

ConfigError identifies a rejected option without retaining caller payloads.

func (*ConfigError) Error added in v0.2.0 

func (e *ConfigError) Error() string

type Console 

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

Console owns a PTY and Session. Start attaches a caller-owned process to a controlling terminal; the caller remains responsible for cancellation and Wait.

func NewConsole 

func NewConsole(opts ...ConsoleOption) (*Console, error)

NewConsole creates a PTY and a Session. Failure closes every acquired handle.

func (*Console) Close 

func (c *Console) Close() error

Close closes the Session and both PTY handles, not any attached process.

func (*Console) GoString added in v0.2.0 

func (p *Console) GoString() string

GoString formats the handle without exposing owned stream or command state.

func (*Console) SendBreak added in v0.2.0 

func (c *Console) SendBreak(ctx context.Context, duration time.Duration) error

SendBreak asserts a terminal break through the serialized Session write path.

func (*Console) Session 

func (c *Console) Session() *Session

Session returns the single owner of Console's matching and sending operations.

func (*Console) SetEcho added in v0.2.0 

func (c *Console) SetEcho(enabled bool) error

SetEcho changes ECHO without changing the terminal's other flags.

func (*Console) SetSize added in v0.2.0 

func (c *Console) SetSize(rows, cols int) error

SetSize changes the terminal dimensions, notifying its foreground process group.

func (*Console) Start added in v0.2.0 

func (c *Console) Start(cmd *exec.Cmd) error

Start attaches cmd to the PTY as a new session with a controlling terminal. The caller owns cancellation and Wait. On success the parent's slave is closed.

func (*Console) String added in v0.2.0 

func (*Console) String() string

String formats the handle without exposing owned stream or command state.

func (*Console) TTY added in v0.1.1 

func (c *Console) TTY() *os.File

TTY returns the slave; the master is intentionally not exposed for competing reads. When attaching manually, release the parent slave after start to observe EOF. Console.Start performs that release automatically.

type ConsoleOption 

type ConsoleOption func(*consoleOptions) error

ConsoleOption configures the PTY adapter.

func WithRaw 

func WithRaw() ConsoleOption

WithRaw configures the slave in raw mode, including disabling echo.

func WithSessionOptions 

func WithSessionOptions(opts ...SessionOption) ConsoleOption

WithSessionOptions configures the Console's underlying Session.

func WithSize added in v0.2.0 

func WithSize(rows, cols int) ConsoleOption

WithSize sets the initial terminal dimensions. The default is 24 rows by 80 columns.

type ErrClass added in v0.2.0 

type ErrClass string

ErrClass is a payload-free error classification. 

const (
	ClassOK          ErrClass = ""
	ClassCanceled    ErrClass = "canceled"
	ClassDeadline    ErrClass = "deadline"
	ClassClosed      ErrClass = "closed"
	ClassBusy        ErrClass = "busy"
	ClassTimeout     ErrClass = "timeout"
	ClassIdleTimeout ErrClass = "idle_timeout"
	ClassEOF         ErrClass = "eof"
	ClassError       ErrClass = "error"
)

Error classes exposed by metadata diagnostics.

func (ErrClass) String added in v0.2.0 

func (c ErrClass) String() string

type Event 

type Event struct {
	Source           MatchSource
	Scope            RuleScope
	RuleIndex        int
	Operation        Op
	CaseIndex, Bytes int
	Error            ErrClass
}

Event contains metadata only. Error is a classification, never a raw message.

type ExpectOption 

type ExpectOption func(*expectOptions) error

ExpectOption configures matching or timing for a single Expect operation.

func WithIdleTimeout 

func WithIdleTimeout(d time.Duration) ExpectOption

WithIdleTimeout limits time without new input; zero disables it.

func WithMatchOrder added in v0.2.0 

func WithMatchOrder(order MatchOrder) ExpectOption

WithMatchOrder selects earliest-byte or declaration-order matching.

func WithNoConsume added in v0.2.0 

func WithNoConsume() ExpectOption

WithNoConsume returns a snapshot without consuming matching input. Handlers must Return.

func WithRules added in v0.2.0 

func WithRules(cases ...Case) ExpectOption

WithRules activates reusable cases alongside foreground cases. Foreground cases win equal-position ties. A zero rule limit means one response per wait.

func WithStreamingFallback added in v0.1.1 

func WithStreamingFallback(handler Handler) ExpectOption

WithStreamingFallback consumes max(1, H/2) bytes when H bytes are pending, where H is min(64 KiB, the session buffer limit), and no ordinary case matches. Result.CaseIndex is -1 and Match is the consumed data. Continue and ContinueKeepTimer both preserve all existing timers.

func WithTimeout 

func WithTimeout(d time.Duration) ExpectOption

WithTimeout sets the relative timer, including elapsed callback time. Zero disables it. Continue can reset it; context deadlines cannot be reset.

type Handler 

type Handler func(context.Context, *Session, Result) (Action, error)

Handler runs after consumption, outside internal locks. It may send or close, but may not call Expect recursively on the same Session.

func ReplyThenContinue added in v0.2.0 

func ReplyThenContinue(text string) Handler

ReplyThenContinue sends text verbatim and continues without resetting timers.

func Then added in v0.2.0 

func Then(response Response) Handler

Then adapts a response to a timer-preserving continuation handler.

type InteractOption added in v0.2.0 

type InteractOption func(*interactOptions) error

InteractOption configures an owned interactive receive operation.

func WithEscape added in v0.2.0 

func WithEscape(key byte) InteractOption

WithEscape sets the local exit byte; the default is control-] (0x1d).

func WithInteractExpectOptions added in v0.2.0 

func WithInteractExpectOptions(opts ...ExpectOption) InteractOption

WithInteractExpectOptions configures matching and timing during interaction.

func WithInteractInputCases added in v0.3.0 

func WithInteractInputCases(cases ...Case) InteractOption

WithInteractInputCases installs ordered, byte-exact local literal actions.

func WithInteractOutputCases added in v0.3.0 

func WithInteractOutputCases(cases ...Case) InteractOption

WithInteractOutputCases adds remote pattern actions; Return ends interaction.

type MatchOrder added in v0.2.0 

type MatchOrder uint8

MatchOrder chooses text-case arbitration within a rule group. 

const (
	Earliest MatchOrder = iota
	Declaration
)

Match orders select earliest-byte or declaration-first arbitration.

type MatchSource added in v0.3.0 

type MatchSource uint8

MatchSource identifies the byte stream evaluated by a match. 

const (
	SourceReceive MatchSource = iota
	SourceInput
)

Sources distinguish remote receive data from local interactive input.

func (MatchSource) String added in v0.3.0 

func (s MatchSource) String() string

type Observer 

type Observer func(Event)

Observer is invoked once per completed public Expect, Send or SendAll operation. Observers run synchronously outside locks and must not block indefinitely.

type Op added in v0.2.0 

type Op string

Op identifies an observed operation. 

const (
	OpExpect  Op = "expect"
	OpSend    Op = "send"
	OpSendAll Op = "send_all"
)

Operation names emitted by completion observers.

func (Op) String added in v0.2.0 

func (o Op) String() string

type Pattern 

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

Pattern is an immutable literal, regular expression, EOF or All pattern. Its zero value is invalid. It never contains per-operation match state.

func All 

func All(patterns ...Pattern) Pattern

All matches all supplied text patterns, in any order, consuming through the last match. Repeated patterns may refer to the same bytes. Captures are omitted.

func Compile 

func Compile(expr string) (Pattern, error)

Compile compiles a Go regular expression. Empty matches are rejected at runtime.

func Default added in v0.2.0 

func Default() Pattern

Default matches a relative timeout or clean EOF when selected in declaration order.

func EOF 

func EOF() Pattern

EOF matches a clean end of input, after buffered text has been matched.

func FromRegexp added in v0.1.1 

func FromRegexp(re *regexp.Regexp) (Pattern, error)

FromRegexp snapshots a compiled expression, including POSIX/Longest semantics. Later changes to the caller's expression do not affect the Pattern.

func FullBuffer added in v0.2.0 

func FullBuffer() Pattern

FullBuffer explicitly accepts a full unmatched buffer and consumes that snapshot.

func Glob added in v0.2.0 

func Glob(pattern string) Pattern

Glob matches unanchored Tcl-style Unicode glob text. Stars cross newlines. Invalid glob declarations fail pattern validation. Literal/Line support raw bytes.

func Line added in v0.1.3 

func Line(text string) Pattern

Line matches a byte-exact final line with optional space, tab and NUL padding. The match includes its preceding CR/LF delimiter and trailing CR/LF bytes. Empty text and text containing CR or LF are invalid declarations.

func Literal 

func Literal(text string) Pattern

Literal matches a nonempty byte string, including arbitrary binary data.

func Timeout added in v0.2.0 

func Timeout() Pattern

Timeout matches the relative wait deadline, never parent cancellation.

func (Pattern) Fold added in v0.2.0 

func (p Pattern) Fold() Pattern

Fold returns an isolated case-insensitive text pattern. Unicode regexp folding applies to Literal and regexp patterns; Line keeps its final-line anchoring. Fold selects Go leftmost-first mode, including for imported POSIX/Longest regexps.

func (Pattern) GoString 

func (p Pattern) GoString() string

GoString formats metadata without exposing payloads.

func (Pattern) IsZero added in v0.1.3 

func (p Pattern) IsZero() bool

IsZero distinguishes an unspecified pattern from a malformed declaration.

func (Pattern) String 

func (p Pattern) String() string

func (Pattern) ValidateText added in v0.1.3 

func (p Pattern) ValidateText() error

ValidateText checks a nonempty text declaration before transport access. EOF and regular expressions matching empty input are not text declarations.

type Redactor added in v0.1.1 

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

Redactor filters one diagnostic stream independently of any Session. Rules, retained prefixes and replacement runs are scoped to this instance. Methods are concurrency safe. Formatting never exposes secrets or retained data.

func NewRedactor added in v0.1.1 

func NewRedactor(secrets []string, replacement string) (*Redactor, error)

NewRedactor copies literal secrets and the nonempty custom replacement.

func (*Redactor) Append added in v0.1.1 

func (r *Redactor) Append(data []byte) []byte

Append returns only bytes that cannot begin a future secret match. It replaces each contiguous union of overlapping or adjacent matches once, across chunks.

func (*Redactor) Finish added in v0.1.1 

func (r *Redactor) Finish() []byte

Finish ends a stream and conservatively masks any retained secret prefix. Repeated calls are empty; the instance may then filter a fresh stream.

func (*Redactor) GoString added in v0.1.1 

func (r *Redactor) GoString() string

GoString formats metadata without exposing payloads.

func (*Redactor) SetSecrets added in v0.1.1 

func (r *Redactor) SetSecrets(secrets []string) ([]byte, error)

SetSecrets ends the old rule scope and returns its safe final bytes. Suspected old secret prefixes are masked before new rules take effect. Invalid rules leave the existing scope untouched. Callers must deliver the returned bytes.

func (*Redactor) String added in v0.1.1 

func (*Redactor) String() string

type Response 

type Response func(context.Context, *Session, Result) error

Response is a borrowed side-effect callback adapted by Then.

func Reply 

func Reply(text string) Response

Reply returns an action that sends text verbatim, including explicit line ends.

type ResponseError 

type ResponseError struct {
	Source               MatchSource
	Scope                RuleScope
	CaseIndex, RuleIndex int
}

ResponseError identifies a response rule that exceeded its per-call limit.

func (*ResponseError) Error 

func (e *ResponseError) Error() string

type Result 

type Result struct {
	Source        MatchSource
	CaseIndex     int
	RuleIndex     int
	Scope         RuleScope
	Start, End    int
	Before, Match string
	Captures      []Capture
}

Result is a detached snapshot of the final match, not the whole conversation. Before contains pending input on failure; CaseIndex is -1 without a match. Explicit fields contain unredacted bytes; formatting emits only metadata.

func ExpectAny added in v0.2.0 

func ExpectAny(ctx context.Context, sessions []*Session, cases []Case, opts ...ExpectOption) (int, Result, error)

ExpectAny reserves all sessions and keeps watching them across continuations. Before/call/After priority applies across sessions; equal groups rotate fairly. Return completes the operation; unconsumed input remains on each session.

func (Result) Buffer added in v0.2.0 

func (r Result) Buffer() string

Buffer returns the raw consumed segment (or the no-consume snapshot).

func (Result) Capture added in v0.2.0 

func (r Result) Capture(name string) (Capture, bool)

Capture returns the first matched named group.

func (Result) GoString 

func (r Result) GoString() string

GoString formats metadata without exposing payloads.

func (Result) Indices added in v0.2.0 

func (r Result) Indices(group int) (int, int, bool)

Indices returns half-open byte offsets within the buffer visible to this match. Group zero is the entire match; higher groups index Captures from one.

func (Result) String 

func (r Result) String() string

type RuleScope added in v0.2.0 

type RuleScope string

RuleScope identifies a persistent or call-scoped rule group. 

const (
	ScopeBefore RuleScope = "before"
	ScopeCall   RuleScope = "call"
	ScopeAfter  RuleScope = "after"
)

Scopes identify the persistent or per-call rule group.

type RuleSnapshot added in v0.2.0 

type RuleSnapshot struct{ Before, After []Case }

RuleSnapshot is a detached declaration snapshot; callback closures remain borrowed.

type Session 

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

Session owns one duplex transport and one matching buffer. The transport must support concurrent Read/Write and guarantee Close interrupts both. After a successful NewSession, callers must not perform I/O on that transport. Expect and Poll are exclusive. Sends are serialized; Close and Redact are concurrency safe. SendAll may queue bounded input for the next Expect. Do not copy a Session. Callback and output execution is cooperative.

func NewSession 

func NewSession(transport io.ReadWriteCloser, opts ...SessionOption) (*Session, error)

NewSession transfers transport ownership only on success. Options are validated before any reads, writes or closes take place.

func (*Session) Close 

func (s *Session) Close() error

Close interrupts I/O and joins owned workers. It never waits for application callbacks or closes borrowed output writers. Repeated calls return the same error.

func (*Session) Expect 

func (s *Session) Expect(ctx context.Context, cases []Case, opts ...ExpectOption) (Result, error)

Expect consumes input through the earliest currently visible match. Ties use declaration order. Continuations consume their match and rescan the remaining buffer, without rereading or replaying bytes. Context cancellation and timeout leave unmatched input available to a subsequent call. Callers must not change the foreground cases until the call returns.

Example 
package main

import (
	"context"
	"fmt"
	"io"
	"net"

	expect "github.com/gatework/go-expect"
)

func main() {
	local, remote := net.Pipe()
	session, err := expect.NewSession(local, expect.WithLineEnding("\r"))
	if err != nil {
		panic(err)
	}
	defer session.Close()
	done := make(chan struct{})
	go func() {
		defer close(done)
		defer remote.Close()
		_, _ = remote.Write([]byte("Password:"))
		b := make([]byte, 7)
		_, _ = io.ReadFull(remote, b)
		_, _ = remote.Write([]byte("router#"))
	}()
	if err = session.Redact("secret"); err != nil {
		panic(err)
	}
	result, err := session.Expect(context.Background(), []expect.Case{
		{Pattern: expect.Literal("Password:"), Handler: expect.ReplyThenContinue("secret\r"), Limit: 1},
		{Pattern: expect.Line("router#")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(result.CaseIndex, result.Match)
	<-done
}

Output:
1 router#

func (*Session) GoString added in v0.2.0 

func (p *Session) GoString() string

GoString formats the handle without exposing owned stream or command state.

func (*Session) Interact added in v0.2.0 

func (s *Session) Interact(ctx context.Context, input io.ReadCloser, output io.Writer, opts ...InteractOption) (err error)

Interact relays through the sole Session receiver. It owns input on successful admission; input.Close must interrupt Read. Output is borrowed and redacted. Escape/EOF cancels and joins the input worker. In-flight write cancellation retains the ordinary Send retirement contract. Remote match tails are bounded by a streaming window of min(64 KiB, buffer limit), not arbitrary regexp prefixes.

func (*Session) InteractTerminal added in v0.2.0 

func (s *Session) InteractTerminal(ctx context.Context, input *os.File, output io.Writer, opts ...InteractOption) (err error)

InteractTerminal temporarily puts a caller-owned local terminal in raw mode. Input is duplicated for cancellation and the original handle remains open. The caller must not read input or change its terminal settings during the call.

func (*Session) Poll added in v0.1.1 

func (s *Session) Poll(ctx context.Context, cases []Case, opts ...ExpectOption) (Result, error)

Poll matches buffered bytes and performs one OS readiness pass without waiting for future input. No match returns ErrTimeout. A zero Expect timeout instead disables that timer and continues waiting. Requires WithOSPolling.

func (*Session) Redact 

func (s *Session) Redact(secrets ...string) error

Redact adds nonempty literal secrets before sending or receiving them. Registration cannot retract bytes already delivered to output writers.

func (*Session) Rules added in v0.2.0 

func (s *Session) Rules() RuleSnapshot

Rules returns the configured persistent declarations without exposing storage.

func (*Session) Send 

func (s *Session) Send(ctx context.Context, text string) (n int, err error)

Send writes text once. No partial write is retried. A failure after entering transport.Write closes the Session and returns its progress in WriteError. An invalid transport count is rejected and reported as zero.

func (*Session) SendAll added in v0.1.1 

func (s *Session) SendAll(ctx context.Context, text string) (int, error)

SendAll drains peer input while writing positive-progress unsent suffixes. Its context owns the complete deadline, including serialization; WithWriteTimeout applies only to Send. Receive data is queued up to WithBufferLimit while the peer writes before reading. Exceeding that bound fails instead of deadlocking. Every error after transport entry closes the Session and reports total progress.

func (*Session) SendAllPoll added in v0.1.1 

func (s *Session) SendAllPoll(ctx context.Context, text string) (int, error)

SendAllPoll uses immediate OS write readiness for every suffix, permitting an initial write without waiting. A blocked suffix returns ErrTimeout with total progress and closes the Session. Requires WithOSPolling.

func (*Session) SendBreak added in v0.2.0 

func (s *Session) SendBreak(ctx context.Context, duration time.Duration) error

SendBreak serializes a transport-specific line break with other writes.

func (*Session) SendLine 

func (s *Session) SendLine(ctx context.Context, text string) (int, error)

SendLine appends the configured line ending (LF by default).

func (*Session) SendNull added in v0.2.0 

func (s *Session) SendNull(ctx context.Context, count int) (int, error)

SendNull sends count literal NUL bytes as one non-retried write.

func (*Session) SendSlow added in v0.2.0 

func (s *Session) SendSlow(ctx context.Context, text string, chunk int, interval time.Duration) (n int, err error)

SendSlow writes byte chunks under one cancellable send lock. The interval is between chunks; it never splits a write retry. Context bounds the whole send.

func (*Session) StartBackground added in v0.2.0 

func (s *Session) StartBackground(ctx context.Context, cases []Case, opts ...ExpectOption) (*Background, error)

StartBackground reserves the receive engine before returning. No competing reader is created; an overlapping foreground wait returns ErrBusy.

func (*Session) String added in v0.2.0 

func (*Session) String() string

String formats the handle without exposing owned stream or command state.

type SessionOption 

type SessionOption func(*sessionOptions) error

SessionOption configures a Session before it takes ownership of the transport.

func WithAfter added in v0.2.0 

func WithAfter(cases ...Case) SessionOption

WithAfter installs session rules consulted after call cases.

func WithBefore added in v0.2.0 

func WithBefore(cases ...Case) SessionOption

WithBefore installs session rules that precede call cases.

func WithBufferLimit 

func WithBufferLimit(n int) SessionOption

WithBufferLimit bounds unconsumed matching input; overflow never discards data.

func WithDefaultTimeout 

func WithDefaultTimeout(d time.Duration) SessionOption

WithDefaultTimeout sets the relative Expect timeout; zero disables it.

func WithLineEnding 

func WithLineEnding(s string) SessionOption

WithLineEnding selects LF, CR or CRLF for SendLine. Send and Reply are verbatim.

func WithLogger 

func WithLogger(logger *slog.Logger) SessionOption

WithLogger enables metadata-only diagnostics; payloads and causes are omitted.

func WithOSPolling added in v0.1.1 

func WithOSPolling() SessionOption

WithOSPolling enables sole-reader OS readiness coordination for Poll and SendAllPoll. The transport must expose syscall.Conn and a nonblocking OS fd. Unsupported transports fail construction before ownership transfers. A working SetReadDeadline(time.Time) error capability selects the runtime poller; otherwise construction selects the bounded native-poll fallback. Wrappers may forward NormalizeReadError(error) error for transport-specific read errors, such as PTY EIO at EOF. Control errors are never normalized.

func WithObserver 

func WithObserver(observers ...Observer) SessionOption

WithObserver adds metadata observers in declaration order.

func WithOutput 

func WithOutput(writers ...io.Writer) SessionOption

WithOutput copies received input through the streaming secret filter. Writers are borrowed, synchronous and must not reenter Session methods. Failure closes the Session; delivery to earlier writers is not replayed.

func WithRemoveNulls added in v0.2.0 

func WithRemoveNulls(enabled bool) SessionOption

WithRemoveNulls explicitly removes NUL bytes from the matching/receive view. The default preserves every transport byte.

func WithSendOutput added in v0.2.0 

func WithSendOutput(writers ...io.Writer) SessionOption

WithSendOutput records actual transport-accepted bytes through a separate streaming secret filter. Writers are borrowed, synchronous and never retried.

func WithStripParity added in v0.2.0 

func WithStripParity(enabled bool) SessionOption

WithStripParity explicitly clears the high bit before optional NUL removal.

func WithTrace added in v0.2.0 

func WithTrace(observers ...TraceObserver) SessionOption

WithTrace enables payload-free candidate diagnostics, independently of completion observers.

func WithWriteTimeout 

func WithWriteTimeout(d time.Duration) SessionOption

WithWriteTimeout bounds each Send, including serialization wait; zero disables it.

type TraceEvent added in v0.2.0 

type TraceEvent struct {
	Source                          MatchSource
	Scope                           RuleScope
	RuleIndex                       int
	CaseIndex, Buffered, Start, End int
	Pattern                         string
	Matched                         bool
}

TraceEvent describes a candidate evaluation without retaining payloads or causes.

type TraceObserver added in v0.2.0 

type TraceObserver func(TraceEvent)

TraceObserver runs synchronously outside locks; it must not reenter Session.

type WriteError 

type WriteError struct {
	Written int
	Cause   error
}

WriteError reports a failed, non-retryable write. Error never prints payloads or the underlying error message; Unwrap exposes the original cause explicitly.

func (*WriteError) Error 

func (e *WriteError) Error() string

func (*WriteError) GoString 

func (e *WriteError) GoString() string

GoString formats metadata without exposing payloads.

func (*WriteError) Unwrap 

func (e *WriteError) Unwrap() error

Source Files

View all Source files

Directories

Path Synopsis
Package conpty runs Windows console programs through an owned pseudoconsole.
 Package conpty runs Windows console programs through an owned pseudoconsole.
examples
dialogue command
Command dialogue runs a local simulated device; no network connection is made.
 Command dialogue runs a local simulated device; no network connection is made.
Package expecttest provides test-owned PTY consoles without logging goroutines.
 Package expecttest provides test-owned PTY consoles without logging goroutines.
internal
redact
Package redact owns incremental coverage and bounded streaming storage.
 Package redact owns incremental coverage and bounded streaming storage.
Package spawn owns the lifecycle of a child with a controlling PTY.
 Package spawn owns the lifecycle of a child with a controlling PTY.

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.