Server Module

Relevant source files

• docs/src/modules/server.yml
• modules/server/src/main/java/com/annimon/ownlang/modules/server/Config.java
• modules/server/src/main/java/com/annimon/ownlang/modules/server/ContextValue.java
• modules/server/src/main/java/com/annimon/ownlang/modules/server/ServerValue.java
• modules/server/src/main/java/com/annimon/ownlang/modules/server/server.java
• ownlang-core/src/main/java/com/annimon/ownlang/lib/Converters.java
• ownlang-core/src/main/java/com/annimon/ownlang/lib/MapValue.java
• ownlang-core/src/main/java/com/annimon/ownlang/lib/ValueUtils.java

The Server Module provides web server capabilities for OwnLang applications through integration with the Javalin web framework. It enables creation of HTTP servers, REST APIs, and static file hosting with comprehensive request/response handling and flexible configuration options.

For network client functionality, see Network and HTTP Modules. For socket-based real-time communication, see Socket Module.

Module Architecture

The server module is built around four main components that work together to provide web server functionality.

Sources: modules/server/src/main/java/com/annimon/ownlang/modules/server/server.java11-46 modules/server/src/main/java/com/annimon/ownlang/modules/server/ServerValue.java10-109 modules/server/src/main/java/com/annimon/ownlang/modules/server/ContextValue.java11-199 modules/server/src/main/java/com/annimon/ownlang/modules/server/Config.java42-128

Core Functions and Types

The module exposes two primary functions and three main types for server operations:

Function	Purpose	Parameters
newServer	Creates configurable server instance	config = {}
serve	Quick static file server	port = 8080, dir = "."

Type	Purpose
ServerValue	Main server object with HTTP method handlers
ContextValue	HTTP request/response context wrapper
Config	Server configuration structure

The module also provides a Header constant containing standard HTTP header names as a map for convenience.

Sources: docs/src/modules/server.yml32-50 docs/src/modules/server.yml51-289

Server Creation and Configuration

Server instances are created through the newServer function, which accepts an optional configuration map. The configuration system maps OwnLang values to Javalin settings.

Sources: modules/server/src/main/java/com/annimon/ownlang/modules/server/Config.java49-87 modules/server/src/main/java/com/annimon/ownlang/modules/server/server.java26-35

HTTP Request Handling

The ServerValue class provides HTTP method handlers that follow a consistent pattern. Each method accepts a path, handler function, and optional roles for access control.

The ServerValue supports all standard HTTP methods: get, post, put, patch, head, delete, and options. It also provides error and exception handlers for error management.

Sources: modules/server/src/main/java/com/annimon/ownlang/modules/server/ServerValue.java20-32 modules/server/src/main/java/com/annimon/ownlang/modules/server/ServerValue.java81-102

Context API

The ContextValue class wraps Javalin's HTTP context, providing access to request data and response manipulation through OwnLang functions.

Key context methods include:

• Request inspection: path(), method(), queryParam(), header()
• Response building: json(), html(), status(), redirect()
• State management: attribute(), cookie(), appData()

Sources: modules/server/src/main/java/com/annimon/ownlang/modules/server/ContextValue.java21-62 docs/src/modules/server.yml97-260

Value System Integration

The server module integrates with OwnLang's value system through converter functions and type checking utilities. The ContextValue extends MapValue to provide function-like access to context operations.

Sources: modules/server/src/main/java/com/annimon/ownlang/modules/server/ContextValue.java25-61 ownlang-core/src/main/java/com/annimon/ownlang/lib/Converters.java128-283 ownlang-core/src/main/java/com/annimon/ownlang/lib/ValueUtils.java104-124

Configuration Options

The server configuration supports comprehensive customization through a map structure:

Category	Options	Purpose
Static Files	webjars, classpathDirs, externalDirs	Static content serving
HTTP	asyncTimeout, defaultContentType, etags, maxRequestSize	HTTP behavior
Jetty	defaultHost, defaultPort	Server binding
Routing	caseInsensitiveRoutes, ignoreTrailingSlashes, contextPath	URL handling
Security	basicAuth, sslRedirects	Authentication and security
Development	dev, showBanner, virtualThreads	Development aids
Application	appData	Custom application data

Sources: modules/server/src/main/java/com/annimon/ownlang/modules/server/Config.java10-40 docs/src/modules/server.yml261-289

Error and Exception Handling

The server provides both error and exception handling mechanisms:

• Error handlers: Handle HTTP status codes with optional content type filtering
• Exception handlers: Handle Java exceptions by class name with custom logic

The error method accepts status codes (numeric or string) and handler functions, while exception requires exception class names and handlers that receive both exception details and context.

Sources: modules/server/src/main/java/com/annimon/ownlang/modules/server/ServerValue.java34-46 modules/server/src/main/java/com/annimon/ownlang/modules/server/ServerValue.java48-63 docs/src/modules/server.yml81-88