Skip to main content

Go Starter Template

High-performance plugin template written in Go with full Socket.IO support.

Overview​

The Go starter template provides a complete, production-ready foundation for building HyperHQ plugins in Go. It features:

  • ✅ Challenge-response authentication
  • ✅ Socket.IO client using googollee/go-socket.io
  • ✅ Concurrent operations with goroutines
  • ✅ Small executable size (~10MB compiled)
  • ✅ Cross-platform builds for Windows, macOS, Linux

Prerequisites​

  • Go 1.21 or later
  • Basic understanding of Go syntax

Quick Start​

1. Get the Template​

Navigate to the templates directory in your HyperHQ installation:

cd "C:\HyperHQ\docs\templates\go-starter"

Or copy the go-starter folder from HyperHQ's docs/templates directory to your development location.

2. Install Dependencies​

go mod download

3. Build​

# Windows
go build -o plugin.exe

# macOS/Linux
go build -o plugin

4. Install in HyperHQ​

# Create plugin directory
mkdir -p "C:/HyperHQ/plugins/my-go-plugin"

# Copy files
cp plugin.exe "C:/HyperHQ/plugins/my-go-plugin/"
cp plugin.json "C:/HyperHQ/plugins/my-go-plugin/"

Key Features​

Authentication​

The template automatically reads authentication credentials from environment variables:

main.go
func NewPlugin() *Plugin {
    pluginID := os.Getenv("HYPERHQ_PLUGIN_ID")
    authChallenge := os.Getenv("HYPERHQ_AUTH_CHALLENGE")
    socketPort := os.Getenv("HYPERHQ_SOCKET_PORT")

    // ... validation and setup
}

Socket.IO Communication​

Full Socket.IO implementation with event handlers:

main.go
client.On("authenticated", func(response map[string]interface{}) {
    if success, ok := response["success"].(bool); ok && success {
        sessionToken = response["sessionToken"].(string)
        registerPlugin()
    }
})

Data Requests​

Helper function for authenticated data requests:

main.go
func (p *Plugin) requestData(method string, params map[string]interface{}) (string, error) {
    requestID := fmt.Sprintf("%s-%d", method, time.Now().UnixNano())

    p.Socket.Emit("request_data", map[string]interface{}{
        "method":       method,
        "params":       params,
        "requestId":    requestID,
        "sessionToken": p.SessionToken,
    })

    return requestID, nil
}

Template Structure​

go-starter/
├── main.go           # Main plugin implementation
├── go.mod            # Go module definition
├── go.sum            # Dependency checksums
├── plugin.json       # Plugin manifest
├── build.sh          # Build script (Unix)
└── build.bat         # Build script (Windows)

Customization​

1. Update Plugin Metadata​

Edit plugin.json:

{
  "id": "my-unique-plugin-id",
  "name": "My Plugin",
  "version": "1.0.0",
  "executable": "plugin.exe"
}

2. Add Your Logic​

Implement custom actions in the Execute method:

main.go
func (p *Plugin) Execute(data map[string]interface{}) interface{} {
    action := data["action"].(string)

    switch action {
    case "my_custom_action":
        return p.handleMyCustomAction(data)
    default:
        return map[string]string{"error": "Unknown action"}
    }
}

3. Handle Events​

Add event listeners in connectToSocketIO:

main.go
client.On("my:custom:event", func(data interface{}) {
    p.handleCustomEvent(data)
})

Building for Production​

Optimize Build Size​

go build -ldflags="-s -w" -o plugin.exe

Cross-Compile​

# For Windows from macOS/Linux
GOOS=windows GOARCH=amd64 go build -o plugin.exe

# For macOS from Windows/Linux
GOOS=darwin GOARCH=amd64 go build -o plugin

# For Linux from Windows/macOS
GOOS=linux GOARCH=amd64 go build -o plugin

Performance Tips​

  1. Use goroutines for concurrent operations
  2. Pool objects to reduce garbage collection
  3. Buffer channels appropriately
  4. Profile with pprof to identify bottlenecks

Troubleshooting​

"Cannot find package"​

go mod tidy
go mod download

"Missing HYPERHQ_PLUGIN_ID"​

The plugin must be launched by HyperHQ. For testing, you can mock environment variables:

export HYPERHQ_PLUGIN_ID="test-plugin"
export HYPERHQ_AUTH_CHALLENGE="test-challenge-123"
export HYPERHQ_SOCKET_PORT="52789"
./plugin

Socket.IO Connection Fails​

  1. Verify HyperHQ is running
  2. Check Socket.IO server is on port 52789
  3. Ensure firewall allows localhost connections

Learn More​