server

package module
v0.2.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 21, 2026 License: MIT Imports: 19 Imported by: 0

README

goserver

Project Badges

goserver

This README documents only the public API exported by the goserver package.

Short summary

  • server provides a specialized HTTP server handler for TinyWASM applications.
  • It operates in two execution modes:
    1. Internal (Default): Runs a lightweight net/http server within the application process. Best for development speed and zero-file generation start.
    2. External: Generates a standalone main Go file, compiles it, and runs it as a separate process. Best for customization and production-like validation.
  • It also supports two compilation modes: In-Memory (default) and On-Disk.
  • It seamlessly handles the transition between execution modes via SetExternalServerMode.

Public API (types and functions)

  • type Config

    • Fields:
      • AppRootDir string
      • SourceDir string (Default: "web")
      • OutputDir string (Default: "web")
      • PublicDir string (Default: "web/public")
      • AppPort string (Default: "8080")
      • Routes []func(mux *http.ServeMux) — Register HTTP handlers for Internal mode.
      • ArgumentsForCompilingServer func() []string
      • ArgumentsToRunServer func() []string
      • Logger func(message ...any)
      • ExitChan chan bool

  • func NewConfig() *Config — returns a new Config with default values.

  • type ServerHandler

    • Construct with: New(c *Config) *ServerHandler
    • Exported methods:
      • StartServer(wg *sync.WaitGroup) — Starts the server (async).
      • SetExternalServerMode(external bool) error — Switches between Internal and External execution modes. When switching to External, it generates files (if missing), compiles, and starts the process.
      • CreateTemplateServer() error — Legacy method specifically for transitioning from Internal to External mode.
      • SetCompilationOnDisk(onDisk bool) — Switches between In-Memory and On-Disk compilation artifacts.
      • RestartServer() error — Restarts the server.
      • NewFileEvent(...) — Handles hot-reloads (recompiles external server or no-op/refresh for internal).
      • MainInputFileRelativePath() string
      • UnobservedFiles() []string

Notes and behaviour

  • Routes Registration: Use Config.Routes to register handlers (e.g., static assets, API endpoints) so they work immediately in Internal mode.
  • Port Management: When switching modes, the handler automatically waits for the port to be free before starting the new strategy.

Minimal usage example

package main

import (
    "fmt"
    "net/http"
    "os"
    "sync"
    "github.com/tinywasm/server"
)

func main() {
    // Define a route function
    myRoute := func(mux *http.ServeMux) {
        mux.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
            fmt.Fprint(w, "Hello from Internal Server!")
        })
    }

    cfg := &server.Config{
        AppRootDir:           ".",
        Routes:               []func(*http.ServeMux){myRoute},
        Logger:               func(messages ...any) { fmt.Fprintln(os.Stdout, messages...) },
    }

    handler := server.New(cfg)

    var wg sync.WaitGroup
    wg.Add(1)
    go handler.StartServer(&wg)
    wg.Wait()
    
    // To switch to external mode later:
    // handler.SetExternalServerMode(true)
}

Contributing

Documentation

Index

Constants

View Source 
const (
	StoreKeyExternalServer = "server_external_mode"
	EnvKeyServerPort       = "SERVER_PORT"
	EnvKeyServerHttps      = "SERVER_HTTPS"
)

Variables

View Source 
var TestMode bool

TestMode is a global flag to indicate the server is running in a test environment. This is used to disable aggressive cleanups and other disruptive behaviors.

Functions

func WaitForPortListening added in v0.1.64 

func WaitForPortListening(port string, timeout time.Duration, https bool) bool

WaitForPortListening waits until the port is accepting HTTP or HTTPS connections (server is ready)

Types

type Config 

type Config struct {
	AppRootDir                  string               // e.g., /home/user/project (application root directory)
	SourceDir                   string               // directory location of main.go e.g., src/cmd/appserver (relative to AppRootDir)
	OutputDir                   string               // compilation and execution directory e.g., deploy/appserver (relative to AppRootDir)
	PublicDir                   string               // default public dir for generated server (e.g., src/web/public)
	MainInputFile               string               // main input file name (default: "main.go", can be "server.go", etc.)
	ArgumentsForCompilingServer func() []string      // e.g., []string{"-X 'main.version=v1.0.0'"}
	ArgumentsToRunServer        func() []string      // e.g., []string{"dev"}
	AppPort                     string               // e.g., 6060
	Https                       bool                 // true if HTTPS is enabled
	DisableGlobalCleanup        bool                 // If true, disables global cleanup in gorun during restarts
	Logger                      func(message ...any) // Logger function
	ExitChan                    chan bool            // Global channel to signal shutdown
	OpenBrowser                 func(port string, https bool)
	Store                       Store                    // Persistent storage for modes
	UI                          UI                       // UI for refresh notifications
	OnExternalModeExecution     func(isExternal bool)    // Called before StartServer to notify mode change
	GitIgnoreAdd                func(entry string) error // Callback to add entries to .gitignore
}

type ServerHandler 

type ServerHandler struct {
	*Config
	// contains filtered or unexported fields
}

func New 

func New() *ServerHandler

New creates a new ServerHandler with default configuration.

func (*ServerHandler) Change added in v0.1.28 

func (h *ServerHandler) Change(newValue string) error

Change implements HandlerEdit.Change

func (*ServerHandler) CreateTemplateServer added in v0.1.16 

func (h *ServerHandler) CreateTemplateServer() error

CreateTemplateServer switches from Internal to External mode. It generates the server files (if not present), compiles, and runs them. This implements the transition from "Internal" to "External" mode.

func (*ServerHandler) Label added in v0.1.28 

func (h *ServerHandler) Label() string

Label implements HandlerEdit.Label

func (*ServerHandler) MainInputFileRelativePath 

func (h *ServerHandler) MainInputFileRelativePath() string

MainInputFileRelativePath returns the path relative to AppRootDir (e.g., "src/cmd/appserver/main.go")

func (*ServerHandler) Name added in v0.1.21 

func (h *ServerHandler) Name() string

func (*ServerHandler) NewFileEvent 

func (h *ServerHandler) NewFileEvent(fileName, extension, filePath, event string) error

event: create,write,remove,rename

func (*ServerHandler) RefreshUI added in v0.1.28 

func (h *ServerHandler) RefreshUI()

func (*ServerHandler) RegisterRoutes added in v0.2.0 

func (h *ServerHandler) RegisterRoutes(fn func(*http.ServeMux))

RegisterRoutes appends fn to the internal route list. Call before StartServer.

func (*ServerHandler) Restart added in v0.1.46 

func (h *ServerHandler) Restart() error

Restart restarts the server. It delegates to the current strategy's Restart method.

func (*ServerHandler) RestartServer 

func (h *ServerHandler) RestartServer() error

func (*ServerHandler) SetAppRootDir added in v0.2.0 

func (h *ServerHandler) SetAppRootDir(dir string)

SetAppRootDir sets the application root directory

func (*ServerHandler) SetCompileArgs added in v0.2.0 

func (h *ServerHandler) SetCompileArgs(fn func() []string)

SetCompileArgs sets the arguments for compiling the server

func (*ServerHandler) SetDisableGlobalCleanup added in v0.2.0 

func (h *ServerHandler) SetDisableGlobalCleanup(disable bool)

SetDisableGlobalCleanup enables or disables global cleanup

func (*ServerHandler) SetExitChan added in v0.2.0 

func (h *ServerHandler) SetExitChan(ch chan bool) *ServerHandler

SetExitChan sets the exit channel

func (*ServerHandler) SetExternalServerMode added in v0.1.19 

func (h *ServerHandler) SetExternalServerMode(external bool) error

SetExternalServerMode switches between Internal and External server strategies. When switching to External, it also: 1. Generates server template files if they don't exist 2. Compiles the server 3. Starts the external process

func (*ServerHandler) SetGitIgnoreAdd added in v0.2.0 

func (h *ServerHandler) SetGitIgnoreAdd(fn func(string) error) *ServerHandler

SetGitIgnoreAdd sets the callback to add entries to .gitignore

func (*ServerHandler) SetHTTPS added in v0.2.0 

func (h *ServerHandler) SetHTTPS(enabled bool) *ServerHandler

SetHTTPS enables or disables HTTPS

func (*ServerHandler) SetLogger added in v0.2.0 

func (h *ServerHandler) SetLogger(fn func(...any)) *ServerHandler

SetLogger sets the logger function

func (*ServerHandler) SetMainInputFile added in v0.2.0 

func (h *ServerHandler) SetMainInputFile(name string)

SetMainInputFile sets the main input file name

func (*ServerHandler) SetOnExternalModeExecution added in v0.2.0 

func (h *ServerHandler) SetOnExternalModeExecution(fn func(bool)) *ServerHandler

SetOnExternalModeExecution sets the callback for external mode execution

func (*ServerHandler) SetOpenBrowser added in v0.2.0 

func (h *ServerHandler) SetOpenBrowser(fn func(port string, https bool)) *ServerHandler

SetOpenBrowser sets the open browser function

func (*ServerHandler) SetOutputDir added in v0.2.0 

func (h *ServerHandler) SetOutputDir(dir string)

SetOutputDir sets the output directory relative to AppRootDir

func (*ServerHandler) SetPort added in v0.2.0 

func (h *ServerHandler) SetPort(port string)

SetPort sets the server port

func (*ServerHandler) SetPublicDir added in v0.2.0 

func (h *ServerHandler) SetPublicDir(dir string) *ServerHandler

SetPublicDir sets the public directory

func (*ServerHandler) SetRunArgs added in v0.2.0 

func (h *ServerHandler) SetRunArgs(fn func() []string)

SetRunArgs sets the arguments for running the server

func (*ServerHandler) SetSourceDir added in v0.2.0 

func (h *ServerHandler) SetSourceDir(dir string)

SetSourceDir sets the source directory relative to AppRootDir

func (*ServerHandler) SetStore added in v0.2.0 

func (h *ServerHandler) SetStore(s Store) *ServerHandler

SetStore sets the persistent store

func (*ServerHandler) SetUI added in v0.2.0 

func (h *ServerHandler) SetUI(ui UI) *ServerHandler

SetUI sets the UI interface

func (*ServerHandler) StartServer 

func (h *ServerHandler) StartServer(wg *sync.WaitGroup)

StartServer initiates the server using the current strategy (In-Memory or External)

func (*ServerHandler) StopServer added in v0.1.24 

func (h *ServerHandler) StopServer() error

StopServer stops the server and waits for the port to be released.

func (*ServerHandler) SupportedExtensions 

func (h *ServerHandler) SupportedExtensions() []string

func (*ServerHandler) UnobservedFiles 

func (h *ServerHandler) UnobservedFiles() []string

UnobservedFiles returns the list of files that should not be tracked by file watchers

func (*ServerHandler) Value added in v0.1.28 

func (h *ServerHandler) Value() string

Value implements HandlerEdit.Value

type ServerStrategy added in v0.1.16 

type ServerStrategy interface {
	Start(wg *sync.WaitGroup) error
	Stop() error
	Restart() error
	HandleFileEvent(fileName, extension, filePath, event string) error
	Name() string
}

type Store added in v0.1.19 

type Store interface {
	Get(key string) (string, error)
	Set(key, value string) error
}

Store defines the minimal interface for persistent storage

type UI added in v0.1.19 

type UI interface {
	RefreshUI()
}

UI defines the minimal interface for UI interaction

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.