Network and HTTP Modules

Relevant source files

• docs/src/modules/http.yml
• docs/src/modules/okhttp.yml
• modules/main/src/main/java/com/annimon/ownlang/modules/http/HttpFunctions.java
• modules/main/src/main/java/com/annimon/ownlang/modules/http/http.java
• modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/HttpClientBuilderValue.java
• modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/HttpClientValue.java
• modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/MultipartBodyBuilderValue.java
• modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/okhttp.java

The Network and HTTP Modules provide web communication capabilities for OwnLang applications. This document covers the http and okhttp modules, which offer different levels of functionality for making HTTP requests, handling responses, and managing web connections.

The http module provides a simple, straightforward interface for basic HTTP operations, while the okhttp module offers advanced features through integration with the OkHttp3 library, including multipart requests, WebSocket support, and fine-grained connection configuration.

For information about the web server capabilities, see Server Module. For general module architecture concepts, see Module Architecture.

Module Overview

The network modules implement two distinct approaches to HTTP communication:

Sources: modules/main/src/main/java/com/annimon/ownlang/modules/http/http.java1-30 modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/okhttp.java1-91 docs/src/modules/http.yml1-95 docs/src/modules/okhttp.yml1-242

HTTP Module

The http module provides a simple interface for HTTP operations through four main functions: http, httpSync, download, and urlencode.

Core Functions

Function	Purpose	Return Type
http	Asynchronous HTTP requests	Boolean (success status)
httpSync	Synchronous HTTP requests	Array [isSuccess, response]
download	Download content as bytes	Byte array
urlencode	URL encode strings	String

HTTP Function Variants

The http function supports multiple call signatures for different use cases:

Sources: modules/main/src/main/java/com/annimon/ownlang/modules/http/HttpFunctions.java53-104 docs/src/modules/http.yml7-62

Request Processing

The HTTP module processes requests through a unified pipeline that handles different parameter combinations:

Sources: modules/main/src/main/java/com/annimon/ownlang/modules/http/HttpFunctions.java106-115 modules/main/src/main/java/com/annimon/ownlang/modules/http/HttpFunctions.java117-138

Request Body Handling

The module supports different request body types based on the input parameters:

Parameter Type	Body Format	Implementation
MapValue	Form data	FormBody.Builder with key-value pairs
String/Other	Raw content	RequestBody.create() with specified content type

Sources: modules/main/src/main/java/com/annimon/ownlang/modules/http/HttpFunctions.java146-184

OkHttp Module

The okhttp module provides comprehensive HTTP functionality through the OkHttp3 library, offering fine-grained control over requests, responses, and client configuration.

Module Structure

Sources: modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/okhttp.java19-35 docs/src/modules/okhttp.yml162-177 docs/src/modules/okhttp.yml90-147

Request Building

The RequestBuilderValue class provides a fluent interface for constructing HTTP requests:

Method	Purpose	Returns
url(url)	Set request URL	RequestBuilderValue
get(), post(), put(), delete()	Set HTTP method	RequestBuilderValue
header(name, value)	Add single header	RequestBuilderValue
headers(headersMap)	Add multiple headers	RequestBuilderValue
newCall(client)	Create executable call	CallValue

Sources: docs/src/modules/okhttp.yml90-147

Multipart Body Support

The module includes comprehensive multipart body creation through MultipartBodyBuilderValue:

Sources: modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/MultipartBodyBuilderValue.java23-70 docs/src/modules/okhttp.yml68-89

Client Configuration

The HttpClientBuilderValue enables detailed HTTP client configuration:

Configuration	Purpose	Time Units Supported
callTimeout	Total call duration limit	millis, seconds, minutes, hours, days
connectTimeout	Connection establishment limit	millis, seconds, minutes, hours, days
readTimeout	Response reading limit	millis, seconds, minutes, hours, days
writeTimeout	Request writing limit	millis, seconds, minutes, hours, days
retryOnConnectionFailure	Retry failed connections	boolean

Sources: modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/HttpClientBuilderValue.java18-47 docs/src/modules/okhttp.yml216-240

WebSocket Support

The module provides WebSocket functionality through callback-based event handling:

Sources: modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/HttpClientValue.java50-123 docs/src/modules/okhttp.yml196-198

Request Body Types

The RequestBodyValue supports multiple content types:

Method	Content Source	Parameters
bytes	Byte array	contentType, bytes, offset, count
file	File system	contentType, filePath
string	String content	contentType, content

Sources: modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/okhttp.java37-75 docs/src/modules/okhttp.yml148-161

Module Integration

Both modules integrate with OwnLang's module system through the standard Module interface:

The http module exposes only functions, while the okhttp module provides both constants (factory objects) and maintains an empty functions map, relying on the constant objects to provide callable functionality.

Sources: modules/main/src/main/java/com/annimon/ownlang/modules/http/http.java15-29 modules/main/src/main/java/com/annimon/ownlang/modules/okhttp/okhttp.java18-35