SDK Guide

Import the SDK:

import "github.com/cyberspacesec/request-mock-skills/pkg/mock"

Core Types

RequestSpec

RequestSpec is the central parameter model, covering 100+ dimensions across 9 functional groups. It supports both flat fields and grouped sub-structures, with group fields taking priority over flat fields.

type RequestSpec struct {
    // Flat fields
    Method              string
    URL                 string
    Headers             map[string]string
    Cookies             []*CookieDetail
    QueryParams         map[string]string
    PostData            *PostDataSpec
    ResponseStatus      int
    ResponseStatusText  string
    ResponseHeaders     map[string]string
    ResponseCookies     []*CookieDetail
    ResponseBody        string
    ResponseMIMEType    string
    ResponseSize        int64
    ServerIP            string
    Connection          string
    PageRef             string
    Priority            string
    ResourceType        string
    Comment             string
    StartedDateTime     string
    Timings             *TimingSpec

    // Functional groups (take priority over flat fields)
    RequestGroup    *RequestGroup
    ResponseGroup   *ResponseGroup
    CacheGroup      *CacheGroup
    TimingGroup     *TimingGroup
    CookieGroup     *CookieGroup
    PostDataGroup   *PostDataGroup
    MetaGroup       *MetaGroup
    InitiatorGroup  *InitiatorGroup
    PageGroup       *PageGroup
}

9 Functional Groups

Group	Fields	Purpose
RequestGroup	scheme, host, port, path, fragment, userinfo, method, headers, query, cookies, postData, mimeType, httpVersion	Full request decomposition
ResponseGroup	status, statusText, httpVersion, headers, cookies, content, redirectURL, bodySize, headersSize, transferSize, mimeType	Full response decomposition
CacheGroup	beforeRequest, afterRequest, comment	Cache state before/after request
TimingGroup	dns, connect, ssl, send, wait, receive, blocked, comment, dnsStart, dnsEnd, connectStart, connectEnd, sslStart, sslEnd, sendStart, sendEnd, receiveStart, receiveEnd, waitStart, waitEnd, blockedStart, blockedEnd, blockedFill	Fine-grained HAR timings
CookieGroup	cookies	Request cookies as HAR Cookie objects
PostDataGroup	mimeType, text, params, comment	Full post data with typed params
MetaGroup	serverIP, connection, comment, priority, resourceType, wallTime, startedDateTime, time, securityState, protocol	Protocol-level metadata
InitiatorGroup	type, url, lineNumber, stack, callFrames	HAR initiator (stack trace)
PageGroup	id, title, startedDateTime, pageTimings, comment	HAR page representation

Generate Functions

Single request

spec := mock.Login("https://api.example.com/login", "alice", "secret")
h, err := mock.GenerateOne(spec)

Multiple specs

specs := []*mock.RequestSpec{spec1, spec2}
h, err := mock.Generate(specs)

Convenience

h, err := mock.GenerateOne(spec)
curl, err := mock.Export(h, mock.FormatCurl)

// One-step
result, err := mock.GenerateAndExport(spec, mock.FormatCurl)

Generator

Generator handles deterministic batch derivation with transforms.

g := mock.NewGenerator(42) // seed for reproducibility
specs := g.GenerateSpecs(baseSpec, 100, mock.DefaultTransforms...)
h, _ := mock.Generate(specs)

Methods

Method	Description
NewGenerator(seed int64)	Create generator with seed
GenerateSpecs(base, n, transforms...)	Derive n specs from base
GenerateSpecsBatch(counts, transforms...)	Derive with per-spec counts

Export

// Basic
curl, err := mock.Export(h, mock.FormatCurl)

// To file
err := mock.ExportToFile(h, mock.FormatCurl, "out.sh")

// With options
data, err := mock.ExportBytes(h, mock.FormatJSON, mock.WithExportIndent(2))

Format constants

mock.FormatCurl       // curl command
mock.FormatWget       // wget command
mock.FormatPython     // Python requests
mock.FormatPostman    // Postman collection v2.1
mock.FormatXML        // HAR XML
mock.FormatYAML       // HAR YAML
mock.FormatHAR        // HAR JSON
mock.FormatJSON       // HAR JSON (alias)
mock.FormatJSONLines  // JSON Lines
mock.FormatCSV        // CSV table
mock.FormatMarkdown   // Markdown table
mock.FormatHTML       // HTML table
mock.FormatText       // Plain text summary

Request Chains

Chain multiple requests sequentially, where each response can influence the next request.

chain := mock.NewChain(g)
chain.AddStep("login", mock.Login("https://api.example.com/login", "alice", "secret"))
chain.AddStep("profile", mock.GetJSON("https://api.example.com/me"))
h, err := chain.Execute()

Engine

The Engine provides a unified entry point accepting a Config object.

cfg := &mock.Config{
    Count:      10,
    Seed:       42,
    Templates:  []mock.TemplateRef{{Name: "getjson", URL: "https://api.example.com/users"}},
    Transforms: []string{"server_ip", "user_agent"},
    Export:     &mock.ExportConfig{Format: "curl"},
}

engine := mock.NewEngine(cfg)

// Synchronous
h, err := engine.Run()
result, err := engine.RunExport()

// Channel streaming
stream, err := engine.RunStream(ctx)
for item := range stream {
    fmt.Println(item.Data)
}

URL Decomposition

When spec.URL is empty but RequestGroup contains decomposition fields (scheme, host, port, path, fragment, userinfo), the composeURL function reconstructs the full URL automatically.

spec := &mock.RequestSpec{
    RequestGroup: &mock.RequestGroup{
        Scheme: "https",
        Host:   "api.example.com",
        Port:   443,
        Path:   "/users",
    },
}
// URL will be composed as "https://api.example.com:443/users"

Config

Config is the YAML/JSON configuration model for batch generation.

cfg, err := mock.LoadConfig("config.yaml")
// or
cfg, err := mock.ParseConfig(yamlData)
h, err := cfg.Run()

Next

• API Reference — full function signatures
• Examples — runnable SDK examples
• Templates — built-in scenario templates