hsmatch

package
v0.9.1 Latest Latest
Warning

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

 Go to latest Published: May 1, 2026 License: BSD-3-Clause, GPL-3.0 Imports: 3 Imported by: 0

Documentation

Overview

Package hsmatch is a thin, build-tag gated wrapper around the gohs (Hyperscan / Vectorscan) library.

It exposes a small block-mode multi-pattern matcher used by netcap to pre-filter input buffers before running heavier RE2 / regexp2 matchers for capture-group extraction.

Build behaviour

  • Default builds (no tag): a stub implementation is compiled. All exported functions return ErrDisabled and callers fall back to their existing regex engine. Zero CGO / C library dependencies.
  • With `-tags hyperscan`: the real implementation backed by github.com/flier/gohs is compiled. Requires libhs (Intel Hyperscan on x86_64 or VectorCamp Vectorscan on ARM/macOS) discoverable via pkg-config (libhs.pc).

Hyperscan does not return submatch offsets – only the (id, from, to) of the overall match. The intended usage pattern is therefore:

  1. Compile a DB from many [Pattern]s once at startup.
  2. For each input buffer call DB.Match; collect the IDs that hit.
  3. For each hit, run the original capture-aware regex (RE2 / regexp2) to extract groups – but only for the small set of patterns that actually matched, not the full pattern list.

Patterns that Hyperscan refuses to compile (e.g. because they use backreferences or other PCRE-only features) are reported via the `rejections` slice returned from Compile – including the original pattern index, expression and the libhs/gohs error message – so the caller can keep these on the existing regex engine and surface useful diagnostics in logs and the web UI.

Runtime counters (scans, matches, scan errors) are exposed through DB.Stats; the optional integration in `decoder/stream/service` aggregates them into a JSON-friendly HyperscanStatus that the web UI exposes at GET /api/hyperscan.

Index

Constants

View Source 
const Enabled = false

Enabled reports whether this build was compiled with Hyperscan support.

Variables

View Source 
var ErrClosed = errors.New("hsmatch: database closed")

ErrClosed mirrors the tagged-build sentinel; never produced here.

View Source 
var ErrDisabled = errors.New("hsmatch: hyperscan support not compiled in (rebuild with -tags hyperscan)")

ErrDisabled is returned by every entry point in this stub build.

Functions

func Compile 

func Compile(patterns []Pattern) (*DB, []Rejection, error)

Compile reports every supplied pattern as rejected and returns ErrDisabled.

Callers are expected to check `Enabled` (or the returned error) and fall back to their pre-existing regex engine.

func RegisterSubsystem 

func RegisterSubsystem(s Subsystem)

RegisterSubsystem adds (or replaces) a subsystem-stats producer keyed by name. Safe to call from package init or from runtime build hooks.

Both build configurations expose this function so registration sites remain unconditional. In stub builds, registered snapshots still flow through Snapshot()/SnapshotMap() — useful for "Enabled: false" surfaces.

func SnapshotMap 

func SnapshotMap() map[string]any

SnapshotMap is a convenience for callers (the web UI) that prefer a map keyed by subsystem name over the ordered slice from Snapshot.

func UnregisterSubsystem 

func UnregisterSubsystem(name string)

UnregisterSubsystem removes a previously registered producer. Used by tests; production code typically registers once at init.

func Version 

func Version() string

Version returns "disabled" in stub builds.

Types

type DB 

type DB struct{}

DB is an opaque placeholder; all methods report ErrDisabled.

func (*DB) Close 

func (d *DB) Close() error

Close is a no-op.

func (*DB) Match 

func (d *DB) Match(_ []byte, _ func(Hit) error) error

Match always returns ErrDisabled.

func (*DB) Stats 

func (d *DB) Stats() Stats

Stats always returns the zero value in stub builds.

type Flag 

type Flag uint32

Flag is a no-op type so callers can declare flags unconditionally. 

const (
	FlagCaseless Flag = 1 << iota
	FlagDotAll
	FlagMultiLine
	FlagSingleMatch
	FlagAllowEmpty
	FlagUtf8
	FlagPrefilter
	FlagSomLeftMost
)

Flag values are placeholders so that callers can reference them in tagged and untagged builds alike.

type Hit 

type Hit struct {
	ID   int
	From uint64
	To   uint64
}

Hit mirrors the tagged-build type.

type NamedSnapshot 

type NamedSnapshot struct {
	Name string `json:"name"`
	Data any    `json:"data"`
}

NamedSnapshot pairs a subsystem name with its current snapshot.

func Snapshot 

func Snapshot() []NamedSnapshot

Snapshot returns the registered subsystem snapshots in deterministic (name-sorted) order so HTTP responses and logs are reproducible.

type Pattern 

type Pattern struct {
	ID    int
	Expr  string
	Flags Flag
}

Pattern mirrors the tagged-build type.

type Rejection 

type Rejection struct {
	Index  int
	ID     int
	Expr   string
	Reason string
}

Rejection mirrors the tagged-build type.

type Stats 

type Stats struct {
	Patterns   int
	Rejections int
	Matches    uint64
	Scans      uint64
	ScanErrors uint64
}

Stats mirrors the tagged-build type.

type Subsystem 

type Subsystem interface {
	Name() string
	Snapshot() any
}

Subsystem returns a free-form, JSON-friendly snapshot of one Hyperscan consumer (service probes, CMS detection, rule engine, …). The exact shape is owned by the consumer — the registry just routes it.

type SubsystemFunc 

type SubsystemFunc struct {
	N string
	F func() any
}

SubsystemFunc adapts a closure into a Subsystem.

func (SubsystemFunc) Name 

func (s SubsystemFunc) Name() string

Name implements Subsystem.

func (SubsystemFunc) Snapshot 

func (s SubsystemFunc) Snapshot() any

Snapshot implements Subsystem.

Source Files

View all Source files

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.