browser

README

browser-go

browser is a small Go library that starts a request to open an HTTP or HTTPS URL in a browser.

A nil return means the launch request was submitted successfully to the operating system or a browser or launcher process started. The package does not wait for or verify browser navigation, and it does not collect browser or launcher output.

package main

import (
    "fmt"

    "github.com/credbind/browser-go"
)

func launchLogin() error {
    if err := browser.Open("https://example.com/login"); err != nil {
        return fmt.Errorf("open login page: %w", err)
    }
    return nil
}

Install it with:

go get github.com/credbind/browser-go

Try it

Run the included example with an HTTP or HTTPS URL:

go run ./example/open https://example.com

By default, the package uses the operating system's configured URL handler:

• macOS: open
• Windows: the native ShellExecuteW API
• Linux, BSDs, AIX, and Solaris: xdg-open, with gio open as a fallback
• WSL: the Windows default browser through PowerShell, with Linux launchers as a fallback

Optional browser override

No configuration is required. By default, Open uses the browser configured as the operating system default.

To explicitly use a different browser, set BROWSER to its executable name or full executable path:

BROWSER=firefox my-program
BROWSER=/usr/bin/google-chrome my-program

macOS

Point BROWSER at the executable inside the application bundle:

BROWSER="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" my-program

WSL

Use the browser's Windows executable through its /mnt/c path:

BROWSER='/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe' \
  go run ./example/open https://github.com/credbind/browser-go

Windows PowerShell

Set BROWSER in the PowerShell environment before running the example:

$env:BROWSER = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
go run .\example\open https://github.com/credbind/browser-go

The value is treated as one executable path, not as a shell command. The URL is passed as exactly one argument. To add browser flags, point BROWSER at a wrapper script. BROWSER and PATH are trusted process configuration; the URL is never interpreted as a shell command.

Only absolute http and https URLs with a host are accepted. Open returns validation and process-start errors to the caller and does not log or exit the calling program.

Print-only operation

Applications that explicitly select a manual browser flow can validate and print the URL without consulting BROWSER or starting any process:

if err := browser.Print(os.Stdout, authorizationURL); err != nil {
    return err
}

Print writes the exact validated URL followed by one newline. It returns writer errors and never silently falls back to launching a browser.

Scope and provenance

This package remains limited to validated HTTP(S) URL opening and explicit printing. It contains no OIDC, OAuth, CredBind token, provider, or SSH protocol behavior. See PROVENANCE.md for the preserved implementation history and LICENSE for the original MIT notice.

Documentation

Overview

Package browser opens HTTP and HTTPS URLs in a user's browser.

By default, Open asks the operating system to use its configured default browser. If BROWSER is set, its value is used as an executable name or path and the URL is passed to that executable as a single argument.

The package starts a launch request and returns without waiting for browser navigation. A nil error does not confirm that the browser displayed the URL. Print is the explicitly selected, launch-free path for showing a validated URL to a user.

Index

• func Open(rawURL string) error
• func OpenContext(ctx context.Context, rawURL string) error
• func Print(writer io.Writer, rawURL string) error

Functions

func Open

func Open(rawURL string) error

Open validates rawURL and starts a request to open it in a browser. Only absolute HTTP and HTTPS URLs with a host are accepted.

If the BROWSER environment variable is set, it must contain an executable name or path. Otherwise, Open asks the operating system to use the user's default browser.

A nil error means the launch request was submitted successfully to the operating system or a browser or launcher process was started. Open does not wait for or verify browser navigation.

func OpenContext

func OpenContext(ctx context.Context, rawURL string) error

OpenContext is like Open, but accepts a context that is checked before the launch begins. A nil context is invalid and causes OpenContext to return an error.

Cancelling ctx after a successful launch cannot close the browser or stop navigation.

func Print

func Print(writer io.Writer, rawURL string) error

Print validates rawURL and writes it followed by one newline. It never consults BROWSER or starts a launcher. Callers use this explicitly selected path when a user must open an authorization URL themselves.