Architecture

Package Structure

request-mock-skills/
│
├── cmd/request-mock/         # CLI entry point (cobra)
│   └── main.go
│
├── pkg/mock/                 # Core library
│   ├── request.go            # RequestSpec parameter model
│   ├── spec_groups.go        # 9 functional groups
│   ├── builder.go            # Generate: spec → *har.Har
│   ├── generator.go          # GenerateOne / MustGenerate
│   ├── batch.go              # Generator / GenerateSpecs
│   ├── transform.go          # Transform abstraction + 16 built-in
│   ├── export.go             # Export dispatch switch
│   ├── export_ext.go         # ExportToFile / ExportBytes / Split
│   ├── convenience.go        # GenerateAndExport & friends
│   ├── config.go             # Config / LoadConfig / ParseConfig
│   ├── engine.go             # Engine unified entry point
│   ├── channel.go            # Channel streaming delivery
│   ├── url_compose.go        # URL decomposition → composition
│   ├── result.go             # Result JSON envelope
│   ├── template.go           # 20 built-in templates
│   ├── options.go            # GenerateOption / PageSpec
│   └── chain.go              # Request chain
│
├── examples/                 # Runnable examples
│   ├── quickstart/
│   ├── batch/
│   ├── engine-streaming/
│   └── config/
│
├── website/docs/             # VitePress documentation
│
├── go.mod
└── go.mod

Key Design Decisions

1. HAR as the canonical intermediate format

All generated requests are represented as *har.Har (from har-skills). Export is a pure function from *har.Har to string. This means:

• Export formats can be added without touching generation logic
• A single generation can be exported to multiple formats
• The HAR file format is the interchange format between CLI commands

2. Spec groups for coverage

The 9 functional groups (RequestGroup, ResponseGroup, CacheGroup, TimingGroup, CookieGroup, PostDataGroup, MetaGroup, InitiatorGroup, PageGroup) cover the full HAR specification plus Chrome extension fields. Group fields take priority over flat fields, enabling both simple usage (flat fields) and full HAR control (groups).

3. Deterministic batch derivation

The Generator uses a seeded math/rand.NewSource to produce identical output across runs and machines. This is essential for reproducible evaluation datasets in security research and testing.

4. Transforms as pluggable functions

Transforms are first-class functions (func(spec *RequestSpec, index int, r *rand.Rand)) that can be composed arbitrarily. The CLI maps string names to transform functions via LookupTransform, and the SDK accepts any function matching the signature.

5. Channel streaming for large batches

The Engine and GenerateStream APIs use Go channels to deliver entries one at a time, enabling streaming export for large batches without holding all results in memory. Three delivery modes are supported: DeliveryEntry (raw *har.Entry), DeliveryExport (formatted export string), and direct channel iteration.

Data Flow

flowchart TB
    Input["CLI flags / Config / SDK"] --> Resolve["Resolve Specifications"]
    Resolve --> Gen["Generate (spec → *har.Har)"]
    Gen --> Post["Post-process (transforms, split, dedup)"]
    Post --> Export["Export (*har.Har → string)"]
    Export --> Out["stdout / file / channel"]

    style Input fill:#e1f5ff
    style Out fill:#e8f5e9

Dependency Graph

flowchart LR
    Mock["pkg/mock"] --> Har["har-skills (pkg/har)"]
    Mock --> Rand["math/rand"]
    Cmd["cmd/request-mock"] --> Mock
    Cmd --> Cobra["github.com/spf13/cobra"]
    Cmd --> Viper["github.com/spf13/viper"]

    style Mock fill:#e3f2fd
    style Har fill:#fff3e0