HttpServer# PRO

The HttpServer class provides a lightweight local HTTP server that can handle HTTP requests, serve static files, and manage WebSocket connections. It is commonly used for local debugging, communication between devices, and serving simple web APIs inside scripts.

#Overview

HttpServer supports:

• Handling custom HTTP routes with programmable handlers
• Serving static files or directories
• Managing WebSocket connections for real-time communication
• Listening on both IPv4 and IPv6
• Configurable ports (including automatic random ports)
• Server state tracking

#Properties

#state: HttpServerState

The current state of the server.

#port: number | null

The port number the server is listening on. If the server is not running, this value is null.

#isIPv4: boolean

Indicates whether the server is listening on an IPv4 address. If false, the server may be using IPv6.

#listenAddressIPv4: string | null

The IPv4 address to listen on. Only used when forceIPv4 is set to true.

#listenAddressIPv6: string | null

The IPv6 address to listen on. Only used when forceIPv6 is set to true.

#Methods

#registerHandler(path: string, handler: (request: HttpRequest) => HttpResponse): void

Registers a handler for a specific request path.

Parameters:

Example:

const server = new HttpServer()

server.registerHandler("/hello", (req) => {
  return HttpResponse.ok(HttpResponseBody.text("Hello, world!"))
})

#registerFile(path: string, filePath: string): void

Registers a single static file for a specific path.

Parameters:

Example:

server.registerFile("/readme", Path.join(Script.directory, "README.md"))

Accessing /readme in the browser returns the file content.

#registerFilesFromDirectory(path: string, directory: string, options?: { defaults?: string[] }): void

Registers a directory of static files to serve.

Parameters:

Example:

server.registerFilesFromDirectory("/static/:file", Path.join(Script.directory, "html"), {
  defaults: ["index.html", "index.htm"]
})

When accessing /static/, the server automatically serves the default index file.

#registerWebsocket(path: string, handlers: WebSocketHandlers): void

Registers a WebSocket handler for the specified path.

Parameters:

WebSocketHandlers type definition:

interface WebSocketHandlers {
  onPong?: (session: WebSocketSession) => void
  onConnected?: (session: WebSocketSession) => void
  onDisconnected?: (session: WebSocketSession) => void
  handleText?: (session: WebSocketSession, text: string) => void
  handleBinary?: (session: WebSocketSession, data: Data) => void
}

Example:

const connectedSessions: WebSocketSession[] = []

server.registerWebsocket("/ws", {
  onConnected: (session) => {
    connectedSessions.push(session)
  },
  onDisconnected: (session) => {
    connectedSessions.splice(connectedSessions.indexOf(session), 1)
  },
  handleText: (session, text) => {
    session.writeText("Echo: " + text)
  }
})

#start(options?: { port?: number; forceIPv4?: boolean }): string | null

Starts the HTTP server.

Parameters:

Returns:

• Returns null if the server starts successfully.
• Returns an error message string if the server fails to start.

Example:

const error = server.start({ port: 8080 })
if (error) {
  console.error("Failed to start:", error)
} else {
  console.log("Server running on port:", server.port)
}

#stop(): void

Stops the HTTP server and releases its resources.

Example:

server.stop()
console.log("Server stopped")

#Type Definitions

#HttpServerState

type HttpServerState = "starting" | "running" | "stopping" | "stopped"

#WebSocketSession

Represents a live WebSocket connection.

Methods:

#Full Example

Below is a complete example of a working HTTP + WebSocket server:

const server = new HttpServer()

// Register a simple HTTP route
server.registerHandler("/api/hello", (req) => {
  return HttpResponse.ok(HttpResponseBody.text("Hello from Scripting Server"))
})

// Serve static files from a directory
server.registerFilesFromDirectory("/public/:file", Path.join(Script.directory, "html"))

// WebSocket chat example
server.registerWebsocket("/chat", {
  onConnected: (session) => {
    console.log("Client connected")
    session.writeText("Welcome to the chat")
  },
  handleText: (session, text) => {
    console.log("Received:", text)
    session.writeText("You said: " + text)
  }
})

// Start the server
const error = server.start({ port: 8080 })
if (error) {
  console.error("Server failed to start:", error)
} else {
  console.log("HTTP Server started on port:", server.port)
}