embed default resources and simplify quick start

Author: daniel-percona

README.md

@@ -31,27 +31,6 @@ tar -xzvf plgm-linux-amd64.tar.gz
 tar -xzvf plgm-darwin-arm64.tar.gz
 ```
 
-2. Create Resources
-
-If you are not cloning the repository, you will need to follow a few extra steps:
-
- A.  Download the [config.yaml](./config.yaml).
-
- B.  Modify the file so that it points to the location of your collection and query definitions.
-
-> **Note:** If you do not create a `default.json` file for your collection and query definitions, you **must** disable the default workload in `config.yaml` (set `default_workload: false`). Otherwise, `plgm` will attempt to load the default workload and fail when the file is not found.
-
-> **Note:** You can specify different locations for both collection and query definitions. Refer to the `config.yaml` file and the instructions below for more details.
-
-> **Tip:** The simplest approach is to clone the repository. This provides all the necessary files and structures, which you can then customize to your liking. (You will still need to download the correct release as mentioned in Step 1).
-
-3.  Once the steps above are complete, you can run `plgm`.
-
-```bash
-# The extracted binary will have the OS suffix
-./plgm-linux-amd64 --version
-```
-
 **Option 2: Build from Source** (Requires Go 1.25+)
 
 This project includes a `Makefile` to simplify building and packaging.
@@ -68,9 +47,42 @@ make build-local
 ./bin/plgm --help
 ```
 
+### 2. Configuration & Resources
+
+To run the application, you need a configuration file. Depending on whether you want to run the built-in test or your own custom workload, you may also need to create resource folders.
+
+**Step A: Get the Config**
+
+Download the [`config.yaml`](./config.yaml) and adjust the `uri` to point to your MongoDB instance.
+
+**Step B: Choose Your Workload**
+
+* **Mode 1: Default Workload (Easiest)**
+    
+    By default (`default_workload: true` in `config.yaml`), the application uses the embedded collection and query definitions. You do **not** need to create any extra folders or files.
+
+* **Mode 2: Custom Workload**
+    
+    To run your own stress tests, you must set `default_workload: false` in `config.yaml` and provide the necessary files:
+
+    1.  **Create Directories**: Create folders for your definitions (e.g., `resources/collections` and `resources/queries`).
+    2.  **Add Files**: Place your JSON schema and query definitions inside these folders.
+    3.  **Update Config**: Ensure `collections_path` and `queries_path` in your `config.yaml` point to these new directories.
+
+    > **Important:** If you are running in Custom Mode, the application expects these folders to exist. If the folders are missing, `plgm` will revert to the embedded defaults to prevent a crash, but your custom test **will not run** until the files are in place.
+
+### 3. Run
+
+Once configured, run the application:
+
+```bash
+# The extracted binary will have the OS suffix
+./plgm-linux-amd64
+```
+
 **Cross-Compilation (Build for different OS)**
 
-If you are preparing binaries for other users (or other servers), use the main build command. This will compile binaries for Linux and Mac and automatically package them into .tar.gz files in the bin/ folder.
+If you are preparing binaries for other users (or other servers), use the main build command. This will compile binaries for Linux and Mac and automatically package them into .tar.gz files in the `bin/` folder.
 
 ```bash
 # Generate all release packages
@@ -82,6 +94,7 @@ make build
 # bin/plgm-darwin-arm64.tar.gz
 ```
 
+
 ### Usage
 
 To view the full usage guide, including available flags and environment variables, run the help command:

internal/config/collections.go

@@ -6,6 +6,8 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+
+	"github.com/Percona-Lab/percona-load-generator-mongodb/resources"
 )
 
 type CollectionField struct {
@@ -43,6 +45,8 @@ type CollectionsFile struct {
 	Collections []CollectionDefinition `json:"collections"`
 }
 
+// LoadCollections attempts to load from disk. If the path is not found,
+// it falls back to the embedded default.json.
 // LoadCollections filters files based on the 'loadDefault' flag.
 // - If loadDefault is TRUE: Load ONLY 'default.json'.
 // - If loadDefault is FALSE: Load ALL files EXCEPT 'default.json'.
@@ -51,13 +55,23 @@ func LoadCollections(path string, loadDefault bool) (*CollectionsFile, error) {
 	if path == "" {
 		return &CollectionsFile{}, nil
 	}
+
+	// 1. Try to access the folder on disk
 	info, err := os.Stat(path)
+
+	// 2. Fallback Logic: If folder/file not found, use Embedded Default
+	if os.IsNotExist(err) {
+		fmt.Printf("Warning: Collections path '%s' not found. Using embedded default.json.\n", path)
+		return loadEmbeddedCollection("collections/default.json")
+	}
+
 	if err != nil {
 		return nil, fmt.Errorf("stat path %s: %w", path, err)
 	}
 
 	var allCollections []CollectionDefinition
 
+	// 3. Normal Disk Loading Logic
 	if info.IsDir() {
 		entries, err := os.ReadDir(path)
 		if err != nil {
@@ -72,12 +86,10 @@ func LoadCollections(path string, loadDefault bool) (*CollectionsFile, error) {
 			isDefault := strings.EqualFold(entry.Name(), "default.json")
 
 			if loadDefault {
-				// Mode: Default Workload -> Load ONLY default.json
 				if !isDefault {
 					continue
 				}
 			} else {
-				// Mode: Custom Workload -> Load EVERYTHING ELSE
 				if isDefault {
 					continue
 				}
@@ -91,7 +103,7 @@ func LoadCollections(path string, loadDefault bool) (*CollectionsFile, error) {
 			allCollections = append(allCollections, loaded.Collections...)
 		}
 	} else {
-		// Single file: Always load it (explicit user choice).
+		// Single file path provided by user
 		loaded, err := loadCollectionsFromFile(path)
 		if err != nil {
 			return nil, err
@@ -102,12 +114,25 @@ func LoadCollections(path string, loadDefault bool) (*CollectionsFile, error) {
 	return &CollectionsFile{Collections: allCollections}, nil
 }
 
+// loadEmbeddedCollection reads a specific file from the embedded FS
+func loadEmbeddedCollection(embedPath string) (*CollectionsFile, error) {
+	b, err := resources.Defaults.ReadFile(embedPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read embedded file %s: %w", embedPath, err)
+	}
+	return parseCollectionsBytes(b)
+}
+
 func loadCollectionsFromFile(path string) (*CollectionsFile, error) {
 	b, err := os.ReadFile(path)
 	if err != nil {
 		return nil, fmt.Errorf("read collections file: %w", err)
 	}
+	return parseCollectionsBytes(b)
+}
 
+// Common parsing logic for both Disk and Embed
+func parseCollectionsBytes(b []byte) (*CollectionsFile, error) {
 	var wrapped CollectionsFile
 	if err := json.Unmarshal(b, &wrapped); err == nil && len(wrapped.Collections) > 0 {
 		return &wrapped, nil
@@ -118,5 +143,5 @@ func loadCollectionsFromFile(path string) (*CollectionsFile, error) {
 		return &CollectionsFile{Collections: arr}, nil
 	}
 
-	return nil, fmt.Errorf("invalid collections format in %s", path)
+	return nil, fmt.Errorf("invalid collections format")
 }

internal/config/queries.go

@@ -6,6 +6,8 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+
+	"github.com/Percona-Lab/percona-load-generator-mongodb/resources"
 )
 
 type QueryDefinition struct {
@@ -32,13 +34,23 @@ func LoadQueries(path string, loadDefault bool) (*QueriesFile, error) {
 	if path == "" {
 		return &QueriesFile{}, nil
 	}
+
+	// 1. Try to access the folder on disk
 	info, err := os.Stat(path)
+
+	// 2. Fallback Logic
+	if os.IsNotExist(err) {
+		fmt.Printf("Warning: Queries path '%s' not found. Using embedded default.json.\n", path)
+		return loadEmbeddedQuery("queries/default.json")
+	}
+
 	if err != nil {
 		return nil, fmt.Errorf("stat path %s: %w", path, err)
 	}
 
 	var allQueries []QueryDefinition
 
+	// 3. Normal Disk Loading Logic
 	if info.IsDir() {
 		entries, err := os.ReadDir(path)
 		if err != nil {
@@ -53,12 +65,10 @@ func LoadQueries(path string, loadDefault bool) (*QueriesFile, error) {
 			isDefault := strings.EqualFold(entry.Name(), "default.json")
 
 			if loadDefault {
-				// Mode: Default Workload -> Load ONLY default.json
 				if !isDefault {
 					continue
 				}
 			} else {
-				// Mode: Custom Workload -> Load EVERYTHING ELSE
 				if isDefault {
 					continue
 				}
@@ -72,7 +82,6 @@ func LoadQueries(path string, loadDefault bool) (*QueriesFile, error) {
 			allQueries = append(allQueries, loaded.Queries...)
 		}
 	} else {
-		// Single file: Always load it.
 		loaded, err := loadQueriesFromFile(path)
 		if err != nil {
 			return nil, err
@@ -83,6 +92,20 @@ func LoadQueries(path string, loadDefault bool) (*QueriesFile, error) {
 	return &QueriesFile{Queries: allQueries}, nil
 }
 
+// loadEmbeddedQuery reads from embedded FS
+func loadEmbeddedQuery(embedPath string) (*QueriesFile, error) {
+	b, err := resources.Defaults.ReadFile(embedPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read embedded file %s: %w", embedPath, err)
+	}
+
+	var defs []QueryDefinition
+	if err := json.Unmarshal(b, &defs); err != nil {
+		return nil, fmt.Errorf("invalid JSON format for embedded queries: %w", err)
+	}
+	return &QueriesFile{Queries: defs}, nil
+}
+
 func loadQueriesFromFile(path string) (*QueriesFile, error) {
 	b, err := os.ReadFile(path)
 	if err != nil {

resources/resources.go

@@ -0,0 +1,6 @@
+package resources
+
+import "embed"
+
+//go:embed collections/default.json queries/default.json
+var Defaults embed.FS