API Reference¶

type Tape struct {
    ID         string         `json:"id"`
    Route      string         `json:"route"`
    RecordedAt time.Time      `json:"recorded_at"`
    Request    RecordedReq    `json:"request"`
    Response   RecordedResp   `json:"response"`
    Metadata   map[string]any `json:"metadata,omitempty"`
    Exemplar   bool           `json:"exemplar,omitempty"`
}

func NewTape(route string, req RecordedReq, resp RecordedResp) Tape
func ValidateTape(t Tape) error
func ValidateExemplar(t Tape) error

type RecordedReq struct {
    Method           string      `json:"method"`
    URL              string      `json:"url"`
    URLPattern       string      `json:"url_pattern,omitempty"`
    Headers          http.Header `json:"headers"`
    Body             []byte      `json:"-"`
    BodyHash         string      `json:"body_hash"`
    Truncated        bool        `json:"truncated,omitempty"`
    OriginalBodySize int64       `json:"original_body_size,omitempty"`
}

type RecordedResp struct {
    StatusCode       int         `json:"status_code"`
    Headers          http.Header `json:"headers"`
    Body             []byte      `json:"-"`
    Truncated        bool        `json:"truncated,omitempty"`
    OriginalBodySize int64       `json:"original_body_size,omitempty"`
    SSEEvents        []SSEEvent  `json:"sse_events,omitempty"`
}

type MediaType struct {
    Type    string            // e.g., "application"
    Subtype string            // e.g., "json"
    Suffix  string            // e.g., "json" (from "+json" structured syntax suffix)
    Params  map[string]string // e.g., {"charset": "utf-8"}
    QValue  float64           // quality factor from Accept header (0.0-1.0, default 1.0)
}

func ParseMediaType(s string) (MediaType, error)
func ParseAccept(accept string) []MediaType
func IsJSON(mt MediaType) bool
func IsText(mt MediaType) bool
func IsBinary(mt MediaType) bool
func MatchesMediaRange(accept, contentType MediaType) bool
func Specificity(mt MediaType) int

func BodyHashFromBytes(b []byte) string // SHA-256 hex hash, empty for nil/empty input

type Recorder struct { /* unexported */ }

func NewRecorder(store Store, opts ...RecorderOption) *Recorder
func (r *Recorder) RoundTrip(req *http.Request) (*http.Response, error) // implements http.RoundTripper
func (r *Recorder) Close() error

type CachingTransport struct { /* unexported */ }

func NewCachingTransport(upstream http.RoundTripper, store Store, opts ...CachingOption) *CachingTransport
func (ct *CachingTransport) RoundTrip(req *http.Request) (*http.Response, error) // implements http.RoundTripper

type Proxy struct { /* unexported */ }

func NewProxy(l1, l2 Store, opts ...ProxyOption) *Proxy
func (p *Proxy) RoundTrip(req *http.Request) (*http.Response, error) // implements http.RoundTripper

type Server struct { /* unexported */ }

func NewServer(store Store, opts ...ServerOption) (*Server, error)
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) // implements http.Handler
func (s *Server) ResetCounter(name string)                         // reset named or all template counters

func BuildTLSConfig(certFile, keyFile, caFile string, insecure bool) (*tls.Config, error)

type Sanitizer interface {
    Sanitize(Tape) Tape
}

type SanitizeFunc func(Tape) Tape

type Pipeline struct { /* unexported */ }

func NewPipeline(funcs ...SanitizeFunc) *Pipeline
func (p *Pipeline) Sanitize(t Tape) Tape // implements Sanitizer

type Faker interface {
    Fake(seed string, original any) any
}

const Redacted = "[REDACTED]"

func DefaultSensitiveHeaders() []string

type Matcher interface {
    Match(req *http.Request, candidates []Tape) (Tape, bool)
}

type MatcherFunc func(req *http.Request, candidates []Tape) (Tape, bool)
func (f MatcherFunc) Match(req *http.Request, candidates []Tape) (Tape, bool)

type Criterion interface {
    Score(req *http.Request, candidate Tape) int
    Name() string
}

type CriterionFunc func(req *http.Request, candidate Tape) int
func (f CriterionFunc) Score(req *http.Request, candidate Tape) int
func (f CriterionFunc) Name() string  // returns "custom"

func DefaultMatcher() *CompositeMatcher          // MethodCriterion + PathCriterion
func ExactMatcher() Matcher                       // first method+path match
func NewCompositeMatcher(criteria ...Criterion) *CompositeMatcher

func ResolveTemplateBodySimple(body []byte, r *http.Request, strict bool) ([]byte, error)

type Store interface {
    Save(ctx context.Context, tape Tape) error
    Load(ctx context.Context, id string) (Tape, error)
    List(ctx context.Context, filter Filter) ([]Tape, error)
    Delete(ctx context.Context, id string) error
}

type Filter struct {
    Route  string
    Method string
}

var ErrNotFound = errors.New("httptape: tape not found")
var ErrInvalidID = errors.New("httptape: invalid tape ID")

func NewMemoryStore(opts ...MemoryStoreOption) *MemoryStore

func NewFileStore(opts ...FileStoreOption) (*FileStore, error)
func WithDirectory(dir string) FileStoreOption  // default: "fixtures"

func ExportBundle(ctx context.Context, s Store, opts ...ExportOption) (io.Reader, error)
func ImportBundle(ctx context.Context, s Store, r io.Reader) error

type Manifest struct {
    ExportedAt      time.Time `json:"exported_at"`
    FixtureCount    int       `json:"fixture_count"`
    Routes          []string  `json:"routes"`
    SanitizerConfig string    `json:"sanitizer_config,omitempty"`
}

type Config struct {
    Version string         `json:"version"`
    Matcher *MatcherConfig `json:"matcher,omitempty"`
    Rules   []Rule         `json:"rules"`
}

type MatcherConfig struct {
    Criteria []CriterionConfig `json:"criteria"`
}

type CriterionConfig struct {
    Type  string   `json:"type"`
    Paths []string `json:"paths,omitempty"`
}

type Rule struct {
    Action  string         `json:"action"`
    Headers []string       `json:"headers,omitempty"`
    Paths   []string       `json:"paths,omitempty"`
    Seed    string         `json:"seed,omitempty"`
    Fields  map[string]any `json:"fields,omitempty"`
}

func LoadConfig(r io.Reader) (*Config, error)
func LoadConfigFile(path string) (*Config, error)
func (c *Config) Validate() error
func (c *Config) BuildPipeline() *Pipeline
func (c *Config) BuildMatcher() *CompositeMatcher // returns nil when no matcher section

cfg := &httptape.Config{
    Version: "1",
    Rules: []httptape.Rule{
        {
            Action: httptape.ActionFake,
            Seed:   "my-seed",
            Fields: map[string]any{
                "$.user.email": "email",
                "$.user.cvv":   map[string]any{"type": "numeric", "length": 3},
            },
        },
    },
}
pipeline := cfg.BuildPipeline()

const (
    ActionRedactHeaders = "redact_headers"
    ActionRedactBody    = "redact_body"
    ActionFake          = "fake"
)

type MockServer struct { *httptest.Server }

func Mock(stubs ...Stub) *MockServer

func When(m Method) *StubBuilder
func (b *StubBuilder) Respond(status int, body ...Body) *StubBuilder
func (b *StubBuilder) WithHeader(key, value string) *StubBuilder
func (b *StubBuilder) Build() Stub

// Method helpers
func GET(path string) Method
func POST(path string) Method
func PUT(path string) Method
func DELETE(path string) Method
func PATCH(path string) Method
func HEAD(path string) Method

// Body helpers
func JSON(s string) Body
func Text(s string) Body
func Binary(b []byte) Body

func LoadFixtures(dir string) (*FileStore, error)
func LoadFixturesFS(fsys fs.FS, dir string) (*MemoryStore, error)