Add file upload support with body_FormData and file_Base64 functions

- Add FileCache for caching local files and remote URLs in memory
- Update body_FormData to accept variadic key-value pairs with file support
  - Use @ prefix for file paths (local or HTTP/HTTPS URLs)
  - Use @@ to escape literal @ values
- Add file_Base64 function for Base64 encoding files
- Update documentation with new syntax and examples

internal/sarin/filecache.go

@@ -0,0 +1,102 @@
+package sarin
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+)
+
+// CachedFile holds the cached content and metadata of a file.
+type CachedFile struct {
+	Content  []byte
+	Filename string
+}
+
+type FileCache struct {
+	cache          sync.Map // map[string]*CachedFile
+	requestTimeout time.Duration
+}
+
+func NewFileCache(requestTimeout time.Duration) *FileCache {
+	return &FileCache{
+		requestTimeout: requestTimeout,
+	}
+}
+
+// GetOrLoad retrieves a file from cache or loads it using the provided source.
+// The source can be a local file path or an HTTP/HTTPS URL.
+func (fc *FileCache) GetOrLoad(source string) (*CachedFile, error) {
+	if val, ok := fc.cache.Load(source); ok {
+		return val.(*CachedFile), nil
+	}
+
+	var (
+		content  []byte
+		filename string
+		err      error
+	)
+	if strings.HasPrefix(source, "http://") || strings.HasPrefix(source, "https://") {
+		content, filename, err = fc.fetchURL(source)
+	} else {
+		content, filename, err = fc.readLocalFile(source)
+	}
+
+	if err != nil {
+		return nil, err
+	}
+
+	file := &CachedFile{Content: content, Filename: filename}
+
+	// LoadOrStore handles race condition - if another goroutine
+	// cached it first, we get theirs (no duplicate storage)
+	actual, _ := fc.cache.LoadOrStore(source, file)
+	return actual.(*CachedFile), nil
+}
+
+func (fc *FileCache) readLocalFile(filePath string) ([]byte, string, error) {
+	content, err := os.ReadFile(filePath) //nolint:gosec
+	if err != nil {
+		return nil, "", fmt.Errorf("failed to read file %s: %w", filePath, err)
+	}
+	return content, filepath.Base(filePath), nil
+}
+
+func (fc *FileCache) fetchURL(url string) ([]byte, string, error) {
+	client := &http.Client{
+		Timeout: fc.requestTimeout,
+	}
+
+	resp, err := client.Get(url)
+	if err != nil {
+		return nil, "", fmt.Errorf("failed to fetch URL %s: %w", url, err)
+	}
+	defer resp.Body.Close() //nolint:errcheck
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, "", fmt.Errorf("failed to fetch URL %s: HTTP %d", url, resp.StatusCode)
+	}
+
+	content, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, "", fmt.Errorf("failed to read response body from %s: %w", url, err)
+	}
+
+	// Extract filename from URL path
+	filename := path.Base(url)
+	if filename == "" || filename == "/" || filename == "." {
+		filename = "downloaded_file"
+	}
+
+	// Remove query string from filename if present
+	if idx := strings.Index(filename, "?"); idx != -1 {
+		filename = filename[:idx]
+	}
+
+	return content, filename, nil
+}

internal/sarin/request.go

@@ -34,11 +34,12 @@ func NewRequestGenerator(
 	cookies types.Cookies,
 	bodies []string,
 	values []string,
+	fileCache *FileCache,
 ) (RequestGenerator, bool) {
 	randSource := NewDefaultRandSource()
 	//nolint:gosec // G404: Using non-cryptographic rand for load testing, not security
 	localRand := rand.New(randSource)
-	templateFuncMap := NewDefaultTemplateFuncMap(randSource)
+	templateFuncMap := NewDefaultTemplateFuncMap(randSource, fileCache)
 
 	pathGenerator, isPathGeneratorDynamic := createTemplateFunc(requestURL.Path, templateFuncMap)
 	methodGenerator, isMethodGeneratorDynamic := NewMethodGeneratorFunc(localRand, methods, templateFuncMap)
@@ -47,7 +48,7 @@ func NewRequestGenerator(
 	cookiesGenerator, isCookiesGeneratorDynamic := NewCookiesGeneratorFunc(localRand, cookies, templateFuncMap)
 
 	bodyTemplateFuncMapData := &BodyTemplateFuncMapData{}
-	bodyTemplateFuncMap := NewDefaultBodyTemplateFuncMap(randSource, bodyTemplateFuncMapData)
+	bodyTemplateFuncMap := NewDefaultBodyTemplateFuncMap(randSource, bodyTemplateFuncMapData, fileCache)
 	bodyGenerator, isBodyGeneratorDynamic := NewBodyGeneratorFunc(localRand, bodies, bodyTemplateFuncMap)
 
 	valuesGenerator := NewValuesGeneratorFunc(values, templateFuncMap)

internal/sarin/sarin.go

@@ -51,6 +51,7 @@ type sarin struct {
 
 	hostClients []*fasthttp.HostClient
 	responses   *SarinResponseData
+	fileCache   *FileCache
 }
 
 // NewSarin creates a new sarin instance for load testing.
@@ -101,6 +102,7 @@ func NewSarin(
 		collectStats:   collectStats,
 		dryRun:         dryRun,
 		hostClients:    hostClients,
+		fileCache:      NewFileCache(time.Second * 10),
 	}
 
 	if collectStats {
@@ -191,7 +193,7 @@ func (q sarin) Worker(
 	defer fasthttp.ReleaseRequest(req)
 	defer fasthttp.ReleaseResponse(resp)
 
-	requestGenerator, isDynamic := NewRequestGenerator(q.methods, q.requestURL, q.params, q.headers, q.cookies, q.bodies, q.values)
+	requestGenerator, isDynamic := NewRequestGenerator(q.methods, q.requestURL, q.params, q.headers, q.cookies, q.bodies, q.values, q.fileCache)
 
 	if q.dryRun {
 		switch {

internal/sarin/template.go

@@ -2,6 +2,8 @@ package sarin
 
 import (
 	"bytes"
+	"encoding/base64"
+	"errors"
 	"math/rand/v2"
 	"mime/multipart"
 	"strings"
@@ -12,7 +14,7 @@ import (
 	"github.com/brianvoe/gofakeit/v7"
 )
 
-func NewDefaultTemplateFuncMap(randSource rand.Source) template.FuncMap {
+func NewDefaultTemplateFuncMap(randSource rand.Source, fileCache *FileCache) template.FuncMap {
 	fakeit := gofakeit.NewFaker(randSource, false)
 
 	return template.FuncMap{
@@ -82,6 +84,21 @@ func NewDefaultTemplateFuncMap(randSource rand.Source) template.FuncMap {
 		"slice_Int":  func(values ...int) []int { return values },
 		"slice_Uint": func(values ...uint) []uint { return values },
 
+		// File
+		// file_Base64 reads a file (local or remote URL) and returns its Base64 encoded content.
+		// Usage: {{ file_Base64 "/path/to/file.pdf" }}
+		//        {{ file_Base64 "https://example.com/image.png" }}
+		"file_Base64": func(source string) (string, error) {
+			if fileCache == nil {
+				return "", errors.New("file cache is not initialized")
+			}
+			cached, err := fileCache.GetOrLoad(source)
+			if err != nil {
+				return "", err
+			}
+			return base64.StdEncoding.EncodeToString(cached.Content), nil
+		},
+
 		// Fakeit / File
 		// "fakeit_CSV": fakeit.CSV(nil),
 		// "fakeit_JSON": fakeit.JSON(nil),
@@ -542,21 +559,75 @@ func (data *BodyTemplateFuncMapData) ClearFormDataContenType() {
 	data.formDataContenType = ""
 }
 
-func NewDefaultBodyTemplateFuncMap(randSource rand.Source, data *BodyTemplateFuncMapData) template.FuncMap {
-	funcMap := NewDefaultTemplateFuncMap(randSource)
+func NewDefaultBodyTemplateFuncMap(
+	randSource rand.Source,
+	data *BodyTemplateFuncMapData,
+	fileCache *FileCache,
+) template.FuncMap {
+	funcMap := NewDefaultTemplateFuncMap(randSource, fileCache)
 
 	if data != nil {
-		funcMap["body_FormData"] = func(kv map[string]string) string {
+		// body_FormData creates a multipart/form-data body from key-value pairs.
+		// Usage: {{ body_FormData "field1" "value1" "field2" "value2" ... }}
+		//
+		// Values starting with "@" are treated as file references:
+		//   - "@/path/to/file.txt" - local file
+		//   - "@http://example.com/file" - remote file via HTTP
+		//   - "@https://example.com/file" - remote file via HTTPS
+		//
+		// To send a literal string starting with "@", escape it with "@@":
+		//   - "@@literal" sends "@literal"
+		//
+		// Example with mixed text and files:
+		//   {{ body_FormData "name" "John" "avatar" "@/path/to/photo.jpg" "doc" "@https://example.com/file.pdf" }}
+		funcMap["body_FormData"] = func(pairs ...string) (string, error) {
+			if len(pairs)%2 != 0 {
+				return "", errors.New("body_FormData requires an even number of arguments (key-value pairs)")
+			}
+
 			var multipartData bytes.Buffer
 			writer := multipart.NewWriter(&multipartData)
 			data.formDataContenType = writer.FormDataContentType()
 
-			for k, v := range kv {
-				_ = writer.WriteField(k, v)
+			for i := 0; i < len(pairs); i += 2 {
+				key := pairs[i]
+				val := pairs[i+1]
+
+				switch {
+				case strings.HasPrefix(val, "@@"):
+					// Escaped @ - send as literal string without first @
+					if err := writer.WriteField(key, val[1:]); err != nil {
+						return "", err
+					}
+				case strings.HasPrefix(val, "@"):
+					// File (local path or remote URL)
+					if fileCache == nil {
+						return "", errors.New("file cache is not initialized")
+					}
+					source := val[1:]
+					cached, err := fileCache.GetOrLoad(source)
+					if err != nil {
+						return "", err
+					}
+					part, err := writer.CreateFormFile(key, cached.Filename)
+					if err != nil {
+						return "", err
+					}
+					if _, err := part.Write(cached.Content); err != nil {
+						return "", err
+					}
+				default:
+					// Regular text field
+					if err := writer.WriteField(key, val); err != nil {
+						return "", err
+					}
+				}
 			}
 
-			_ = writer.Close()
-			return multipartData.String()
+			if err := writer.Close(); err != nil {
+				return "", err
+			}
+			return multipartData.String(), nil
 		}
 	}