browser

Documentation

Overview

Package browser provides utilities for launching URLs in the user's web browser. It supports Windows, macOS, and Linux with automatic detection of the system default browser. The package handles cross-platform differences in browser launch commands and provides options for controlling launch behavior.

Package browser provides secure cross-platform utilities for launching URLs in web browsers.

This package handles the complexity of opening URLs in the system default browser across Windows, macOS, and Linux, with built-in security validation and timeout handling. It prevents command injection and validates that only http/https URLs are opened.

Key Features

• Launch URLs in system default browser
• Cross-platform command construction (Windows/macOS/Linux)
• Non-blocking launch with configurable timeout
• Target options (default browser, system browser, none)
• URL validation (http/https only, prevents file:// and javascript:)
• Command injection prevention

Security Considerations

This package enforces strict URL validation to prevent security issues:

• Only http:// and https:// schemes are allowed
• URLs are validated before passing to shell commands
• No user-controlled data is directly interpolated into commands

Cross-Platform Behavior

On Windows:

• Uses "cmd /c start" command with empty title to avoid URL parsing issues
• Handles URL escaping for cmd.exe

On macOS:

• Uses "open" command
• Automatically opens in default browser

On Linux:

• Uses "xdg-open" command (most common)
• Falls back to "sensible-browser" if xdg-open unavailable

Browser Targets

The package supports three browser targets:

• TargetDefault: Uses the system default browser (alias for TargetSystem)
• TargetSystem: Uses the system default browser
• TargetNone: Disables browser launching

Example Usage

Basic usage - launch in default browser:

err := browser.Launch(browser.LaunchOptions{
    URL:    "https://example.com",
    Target: browser.TargetDefault,
})
if err != nil {
    log.Printf("Failed to launch browser: %v", err)
}

Launch with custom timeout:

err := browser.Launch(browser.LaunchOptions{
    URL:     "https://example.com",
    Target:  browser.TargetSystem,
    Timeout: 10 * time.Second,
})
if err != nil {
    log.Printf("Failed to launch browser: %v", err)
}

Disable browser launching:

err := browser.Launch(browser.LaunchOptions{
    URL:    "https://example.com",
    Target: browser.TargetNone,
})
// No browser will be launched, err will be nil

Validate browser target from user input:

userInput := "default"
if !browser.IsValid(userInput) {
    log.Fatalf("Invalid browser target. Valid targets: %s",
        browser.FormatValidTargets())
}

Get display name for user feedback:

target := browser.TargetSystem
fmt.Printf("Opening in %s...\n", browser.GetTargetDisplayName(target))
// Output: Opening in default browser...

Error Handling

The Launch function is non-blocking and returns immediately. Any errors during the actual browser launch are logged to stderr but do not cause the program to fail. This is intentional because browser launching is typically a non-critical operation.

However, Launch will return an error immediately for invalid URL schemes:

err := browser.Launch(browser.LaunchOptions{
    URL:    "file:///etc/passwd", // Invalid scheme
    Target: browser.TargetSystem,
})
if err != nil {
    // Error: invalid URL scheme: URL must start with http:// or https://
}

Thread Safety

All functions in this package are safe for concurrent use.

Index

• func FormatValidTargets() string
• func GetTargetDisplayName(target Target) string
• func IsValid(target string) bool
• func Launch(opts LaunchOptions) error
• type LaunchOptions
• type Target
  • func ResolveTarget(target Target) Target
  • func ValidTargets() []Target

Functions

func FormatValidTargets

func FormatValidTargets() string

FormatValidTargets returns a comma-separated list of valid targets.

func GetTargetDisplayName

func GetTargetDisplayName(target Target) string

GetTargetDisplayName returns a human-readable name for the browser target.

func IsValid

func IsValid(target string) bool

IsValid checks if a target string is valid.

func Launch

func Launch(opts LaunchOptions) error

Launch opens the specified URL in the browser determined by the target. Returns an error if the launch fails, but this is not critical. The function is non-blocking and launches the browser in a separate goroutine.

Types

type LaunchOptions

type LaunchOptions struct {
	// URL to open
	URL string
	// Target browser to use
	Target Target
	// Timeout for the launch command (default 5 seconds)
	Timeout time.Duration
}

LaunchOptions contains options for launching a browser.

type Target

type Target string

Target represents the browser target for launching URLs.

const (
	// TargetDefault uses the system default browser
	TargetDefault Target = "default"
	// TargetSystem uses the system default browser (alias for TargetDefault)
	TargetSystem Target = "system"
	// TargetNone disables browser launching
	TargetNone Target = "none"
)

func ResolveTarget

func ResolveTarget(target Target) Target

ResolveTarget determines the actual browser target to use. Converts "default" to "system", and respects "none".

func ValidTargets

func ValidTargets() []Target

ValidTargets returns all valid browser target values.