server

README

goserver

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
• Variables
• type Config
  • func NewConfig() *Config
• type ServerHandler
  • func New(c *Config) *ServerHandler
  • func (h *ServerHandler) Change(newValue string)
  • func (h *ServerHandler) CreateTemplateServer() error
  • func (h *ServerHandler) Label() string
  • func (h *ServerHandler) MainInputFileRelativePath() string
  • func (h *ServerHandler) Name() string
  • func (h *ServerHandler) NewFileEvent(fileName, extension, filePath, event string) error
  • func (h *ServerHandler) RefreshUI()
  • func (h *ServerHandler) RestartServer() error
  • func (h *ServerHandler) SetCompilationOnDisk(onDisk bool)
  • func (h *ServerHandler) SetExternalServerMode(external bool) error
  • func (h *ServerHandler) SetLog(f func(message ...any))
  • func (h *ServerHandler) StartServer(wg *sync.WaitGroup)
  • func (h *ServerHandler) StopServer() error
  • func (h *ServerHandler) SupportedExtensions() []string
  • func (h *ServerHandler) UnobservedFiles() []string
  • func (h *ServerHandler) Value() string
• type ServerStrategy
• type Store
• type UI

Constants

const StoreKeyCompilationOnDisk = "server_compilation_ondisk"

const StoreKeyExternalServer = "server_external_mode"

Variables

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.

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., 8080
	Routes                      []func(*http.ServeMux) // Functions to register routes on the HTTP server
	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
	Store                       Store                  // Persistent storage for modes
	UI                          UI                     // UI for refresh notifications
}

func NewConfig

func NewConfig() *Config

NewConfig provides a default configuration.

type ServerHandler

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

func New

func New(c *Config) *ServerHandler

func (*ServerHandler) Change

func (h *ServerHandler) Change(newValue string)

Change implements HandlerEdit.Change

func (*ServerHandler) CreateTemplateServer

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

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

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

func (h *ServerHandler) RefreshUI()

func (*ServerHandler) RestartServer

func (h *ServerHandler) RestartServer() error

func (*ServerHandler) SetCompilationOnDisk

func (h *ServerHandler) SetCompilationOnDisk(onDisk bool)

SetCompilationOnDisk sets whether the server artifacts should be written to disk.

func (*ServerHandler) SetExternalServerMode

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) SetLog

func (h *ServerHandler) SetLog(f func(message ...any))

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

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

func (h *ServerHandler) Value() string

Value implements HandlerEdit.Value

type ServerStrategy

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

type Store

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

Store defines the minimal interface for persistent storage

type UI

type UI interface {
	RefreshUI()
}

UI defines the minimal interface for UI interaction