goserver

README

goserver

goserver is a Go package that encapsulates the logic for running a development and production server. It automatically manages static file serving, external Go server compilation, hot-reloading, and process control, making it easy to switch between development and production modes.

Note: goserver now prefers an external Go server file (e.g. main.server.go). If that file is missing the package will generate it from an embedded Markdown template (located in templates/server_definition.md), extracting the Go code blocks and writing them to the configured output path. The generator substitutes three template variables: AppPort, PublicFolder and RootFolder. Importantly, the generator never overwrites an existing external server file.

Basic Usage Example

Here is a minimal example of how to use goserver in your Go project:

package main

import (
	"fmt"
	"os"
	"sync"
	"github.com/cdvelop/goserver"
)

func main() {
	config := &goserver.Config{
		RootFolder:               "./web",
		MainFileWithoutExtension: "main.server",
		ArgumentsForCompilingServer: func() []string { return []string{} },
		ArgumentsToRunServer:        func() []string { return []string{} },
		PublicFolder:             "public",
		AppPort:                  "8080",
		Logger:                   os.Stdout,
		ExitChan:                 make(chan bool),
	}

	handler := goserver.New(config)

	var wg sync.WaitGroup
	wg.Add(1)
	go handler.Start(&wg)

	// Wait for server to finish (in real use, handle signals for graceful shutdown)
	wg.Wait()
	fmt.Println("Server stopped.")
}

Public API

Main Types

• Config
  Configuration structure for the server.

  • RootFolder: Project root folder.
  • MainFileWithoutExtension: Base name of the main server file (without extension).
  • ArgumentsForCompilingServer: Function returning arguments for compiling the server.
  • ArgumentsToRunServer: Function returning arguments for running the server.
  • PublicFolder: Static files folder.
  • AppPort: Application port.
  • Logger: Output for logs.
  • Generator behavior: when the external main server file is missing, goserver will create it from an embedded Markdown template. The generator performs simple templating for AppPort, PublicFolder and RootFolder, extracts Go code fenced blocks and writes a single main package file. It will not overwrite an existing file.
  • ExitChan: Channel to signal shutdown.

• ServerHandler
  Main server handler, created with New(*Config).

Main Methods

• New(c *Config) *ServerHandler
  Creates a new server handler.

• (*ServerHandler) Start(wg *sync.WaitGroup)
  Starts the server (internal or external) as a goroutine.

• (*ServerHandler) StartExternalServer() error
  Compiles and runs the external server.

• (*ServerHandler) StartInternalServerFiles()
  Starts an internal HTTP server for static files.

• (*ServerHandler) StopInternalServer() error
  Stops the internal server.

• (*ServerHandler) RestartInternalServer() error
  Restarts the internal server.

• (*ServerHandler) RestartExternalServer() error
  Restarts the external server (stops, recompiles, and runs).

• (*ServerHandler) RestartServer() (string, error)
  Restarts the current server (internal or external) and returns a status message.

• (*ServerHandler) NewFileEvent(fileName, extension, filePath, event string) error
  Handles file events (create, write, etc.) for hot-reload.

• (*ServerHandler) MainFilePath() string
  Returns the path to the main server file.

• (*ServerHandler) Name() string
  Returns the server name ("GoServer").

• (*ServerHandler) UnobservedFiles() []string
  Returns files that should not be watched (executables, temporary files).

Documentation

Index

• type Config
• type ServerHandler
  • func New(c *Config) *ServerHandler
  • func (h *ServerHandler) MainFilePath() string
  • func (h *ServerHandler) Name() string
  • func (h *ServerHandler) NewFileEvent(fileName, extension, filePath, event string) error
  • func (h *ServerHandler) RestartExternalServer() error
  • func (h *ServerHandler) RestartServer() (string, error)
  • func (h *ServerHandler) StartExternalServer() error
  • func (h *ServerHandler) StartServer(wg *sync.WaitGroup)
  • func (h *ServerHandler) UnobservedFiles() []string
• type ServerTemplateData

Types

type Config

type Config struct {
	RootFolder                  string          // e.g., web
	MainFileWithoutExtension    string          // e.g., main.server
	ArgumentsForCompilingServer func() []string // e.g., []string{"-X 'main.version=v1.0.0'"}
	ArgumentsToRunServer        func() []string // e.g., []string{"dev"}
	PublicFolder                string          // e.g., public
	AppPort                     string          // e.g., 8080
	Logger                      io.Writer       // For logging output
	ExitChan                    chan bool       // Global channel to signal shutdown
}

type ServerHandler

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

func New

func New(c *Config) *ServerHandler

func (*ServerHandler) MainFilePath

func (h *ServerHandler) MainFilePath() string

MainFilePath eg: <root>/web/main.server.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) RestartExternalServer

func (h *ServerHandler) RestartExternalServer() error

func (*ServerHandler) RestartServer

func (h *ServerHandler) RestartServer() (string, error)

RestartServer reinicia el servidor externo y devuelve un mensaje de estado

func (*ServerHandler) StartExternalServer

func (h *ServerHandler) StartExternalServer() error

func (*ServerHandler) StartServer

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

Start inicia el servidor como goroutine

func (*ServerHandler) UnobservedFiles

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

UnobservedFiles returns the list of files that should not be tracked by file watchers eg: main.exe, main_temp.exe

type ServerTemplateData

type ServerTemplateData struct {
	AppPort      string
	PublicFolder string
	RootFolder   string
}