Sandbox

Useful playgrounds for testing custom functions

Technology

Golang
Project Forge

The sandbox module provides interactive testing environments for Project Forge applications. It enables developers to create custom playgrounds for experimenting with application features, testing new functionality, and prototyping code in a safe, isolated environment.

Overview

This module provides:

Key Features

Development & Testing

Customization

Safety & Monitoring

Package Structure

Core Framework

Web Interface

Templates

Usage

Creating a New Sandbox

Add a new sandbox by creating a Sandbox struct, and registering it in the AllSandboxes slice:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var mySandbox = &Sandbox{
    Key:   "my-test",
    Title: "My Test Environment",
    Icon:  "beaker",
    Args: util.FieldDescs{
        {Key: "message", Title: "Message", Type: "string", Default: "Hello"},
        {Key: "count", Title: "Count", Type: "int", Default: "5"},
    },
    Run: onMyTest,
}

func onMyTest(ctx context.Context, st *app.State, args util.ValueMap, logger util.Logger) (any, error) {
    message := args.GetStringOr("message", "default")
    count := args.GetIntOr("count", 1)

    result := util.ValueMap{
        "message": message,
        "repeated": strings.Repeat(message+" ", count),
        "timestamp": util.TimeCurrent(),
    }

    return result, nil
}

Accessing Sandboxes

Sandboxes are accessible through the admin web interface:

  1. Navigate to /admin/sandbox to see all available sandboxes
  2. Click on a specific sandbox to access its interface
  3. Fill in required parameters (if any)
  4. Execute the sandbox function and view results

URL Structure

Integration

Menu System

The sandbox module automatically registers with the admin menu: - Main menu item: “Sandboxes” - Submenu items: Individual sandboxes - Dynamic menu generation based on available sandboxes

Telemetry

All sandbox executions are traced with OpenTelemetry: - Span name: sandbox.{key} - Automatic performance monitoring - Error tracking and logging

Error Handling

Advanced Features

Custom Result Rendering

Specific sandboxes can have custom result templates: - Default: Generic result display - Custom: Specialized rendering (e.g., testbed template) - Conditional: Module-dependent rendering (e.g., WASM support)

Parameter Types

Supports various parameter types through field descriptors: - string: Text input - int: Numeric input - bool: Checkbox input - select: Dropdown selection - textarea: Multi-line text input

Security Considerations

Source Code

See Also