Skip to main content

Go Starter Template

This download is a legacy Go example. The supplied main.go calls socketio.Client and socketio.NewClient, while go.mod selects the googollee/go-socket.io server package. Resolve this client-library mismatch before using the build instructions below. The download is not a validated working starter.

Use the Plugin Developer Guide as the current protocol reference.

Overview​

The Go starter demonstrates executable plugin communication. Validate the build, authentication, reconnect, and shutdown before publishing. Features include:

  • Challenge-response authentication
  • Socket.IO connection code requiring a compatible client dependency
  • 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​

Download the go starter and extract the archive. Open a terminal in the extracted folder:

cd go-starter

Use Build and install on Linux for Linux. The numbered build and install example below targets Windows.

2. Install Dependencies​

go mod download

3. Build​

# Windows
go build -o plugin.exe

# macOS/Linux
go build -o plugin

4. Install in HyperHQ on Windows​

Use the HyperSpin root shown in Settings, Paths. Replace this example with your configured plugin folder.

$pluginDir = 'C:/ProgramData/HyperSpin/plugins/my-go-plugin'
New-Item -ItemType Directory -Force -Path $pluginDir
Copy-Item -Path 'plugin.exe' -Destination $pluginDir
Copy-Item -LiteralPath 'plugin.json' -Destination $pluginDir

Build and install on Linux​

Run these commands inside the extracted starter directory on Linux:

go mod download
go build -o plugin

Set executableProviders.linux to plugin in plugin.json. Copy the executable and manifest into your configured plugin directory:

plugin_dir="/absolute/path/to/plugins/my-go-plugin"
mkdir -p "$plugin_dir"
cp plugin plugin.json "$plugin_dir/"
chmod +x "$plugin_dir/plugin"

Replace the example directory with your configured plugin path. Restart or reload the plugin in HyperHQ and verify authentication, an action, and shutdown. Follow the Linux release requirements before publishing.

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",
  "executableProviders": {
    "windows": "plugin.exe",
    "linux": "plugin"
  }
}

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
# For Windows, use -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"​

Launch through HyperHQ for a real authenticated session. Mock environment variables only for a local fixture using matching test credentials:

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. Read the active port from HYPERHQ_SOCKET_PORT. The launch port varies.
  3. Ensure firewall allows localhost connections

Learn More​