Class CaddyClient

Client for interacting with Caddy Admin API

Constructors

constructor

new CaddyClient(options?: CaddyClientOptions): CaddyClient
Create a new Caddy API client
Parameters
- options: CaddyClientOptions = {}
  Client configuration options
Returns CaddyClient
Throws
If options are invalid (e.g., invalid URL or timeout)
- Defined in src/caddy/client.ts:53

Methods

adapt

adapt(
config: string,
adapter?: string,
): Promise<Config & Record<string, unknown>>
Adapt a configuration from one format to another Commonly used to convert Caddyfile to JSON configuration.
Parameters
- config: string
  The configuration content to adapt
- adapter: string = "caddyfile"
  The adapter to use (e.g., "caddyfile", "json", "yaml", "nginx", "apache")
Returns Promise<Config & Record<string, unknown>>
The adapted configuration as validated JSON

Throws
If config or adapter parameters are invalid

Throws
If Caddy cannot parse the configuration

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
- Defined in src/caddy/client.ts:560

addRoute

addRoute(server: string, route: CaddyRoute): Promise<boolean>
Add a route to a server
Parameters
- server: string
  Server name
- route: CaddyRoute
  Route configuration
Returns Promise<boolean>
True if route was added, false if already exists

Throws
If route configuration is invalid

Throws
If Caddy API returns an error response

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
- Defined in src/caddy/client.ts:179

addRoutes

addRoutes(
server: string,
routes: CaddyRoute[],
): Promise<{ added: number; skipped: number }>
Add multiple routes to a server (convenience method to avoid loops) This method adds routes one at a time and handles idempotency for each.

Performance: Fetches existing routes once and caches them to avoid N+1 API calls.
Parameters
- server: string
  Server name
- routes: CaddyRoute[]
  Array of routes to add
Returns Promise<{ added: number; skipped: number }>
Object with counts of added and skipped routes
Throws
If any route configuration is invalid

Throws
If Caddy API returns an error response

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
Example
```
const routes = buildServiceRoutes({ host: "api.localhost", dial: "localhost:3000" });
const result = await client.addRoutes("https_server", routes);
console.log(`Added ${result.added}, skipped ${result.skipped}`);
```
- Defined in src/caddy/client.ts:225

applyConfig

applyConfig(config: Config | Config & Record<string, unknown>): Promise<void>
Apply a full configuration to Caddy

Replaces the entire running Caddy configuration with the provided config object. This is the primary method for applying loaded or modified configurations.
Parameters
- config: Config | Config & Record<string, unknown>
  Full Caddy configuration object
Returns Promise<void>
Throws
If config is invalid

Throws
If Caddy rejects the configuration

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
Example
```
// Load, modify, and apply configuration
const config = await loadCaddyfile("./Caddyfile");

// Modify the config
config.apps.http.servers.srv0.routes.push(
  buildHostRoute({ host: "api.example.com", dial: "localhost:3000" })
);

// Apply to running Caddy
await client.applyConfig(config);
```
- Defined in src/caddy/client.ts:602

getConfig

getConfig(): Promise<Config & Record<string, unknown>>
Get current Caddy configuration

Returns Promise<Config & Record<string, unknown>>
Full Caddy configuration as JSON, validated against Caddy schema

Throws
If Caddy API returns an error response

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
- Defined in src/caddy/client.ts:124

getRoutes

getRoutes(server: string): Promise<CaddyRoute[]>
Get routes for a specific server
Parameters
- server: string
  Server name (e.g., "https_server")
Returns Promise<CaddyRoute[]>
Array of routes, validated against Caddy route schema

Throws
If Caddy API returns an error response

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
- Defined in src/caddy/client.ts:152

getServerConfig

getServerConfig(server: string): Promise<Server & Record<string, unknown>>
Get configuration for a specific server
Parameters
- server: string
  Server name
Returns Promise<Server & Record<string, unknown>>
Server configuration object, validated against Caddy schema

Throws
If Caddy API returns an error response

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
- Defined in src/caddy/client.ts:369

getServers

getServers(): Promise<Record<string, Server & Record<string, unknown>>>
Get information about all servers

Returns Promise<Record<string, Server & Record<string, unknown>>>
Server configurations, validated against Caddy schema

Throws
If Caddy API returns an error response

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
- Defined in src/caddy/client.ts:355

getUpstreams

getUpstreams(): Promise<UpstreamStatus[]>
Get reverse proxy upstream status Returns the current state of all configured upstream servers.

Returns Promise<UpstreamStatus[]>
Array of upstream server status objects, validated

Throws
If Caddy API returns an error response

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
- Defined in src/caddy/client.ts:543

getVersion

getVersion(): Promise<{ version?: string } & Record<string, unknown>>
Get Caddy version information

Returns Promise<{ version?: string } & Record<string, unknown>>
Version information object with version string and additional metadata
- Defined in src/caddy/client.ts:402

insertRoute

insertRoute(
    server: string,
    route: CaddyRoute,
    position?: "beginning" | "end" | "after-health-checks",
): Promise<void>
Insert a route at a specific position in the server's route list
Parameters
- server: string
  Server name
- route: CaddyRoute
  Route to insert
- position: "beginning" | "end" | "after-health-checks" = "after-health-checks"
  Where to insert the route
Returns Promise<void>
void
- Defined in src/caddy/client.ts:415

patchRoutes

patchRoutes(server: string, routes: CaddyRoute[]): Promise<void>
Replace all routes for a server (PATCH)
Parameters
- server: string
  Server name
- routes: CaddyRoute[]
  Array of routes
Returns Promise<void>
Throws
If any route configuration is invalid

Throws
If Caddy API returns an error response

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
- Defined in src/caddy/client.ts:297

patchServer

patchServer(
serverConfig: Record<string, Partial<Server> | Record<string, unknown>>,
): Promise<void>
Patch server configuration
Parameters
- serverConfig: Record<string, Partial<Server> | Record<string, unknown>>
  Server configuration object (server name -> server config)
Returns Promise<void>
- Defined in src/caddy/client.ts:380

reload

reload(): Promise<void>
Reload Caddy configuration

Returns Promise<void>
- Defined in src/caddy/client.ts:392

removeRouteById

removeRouteById(server: string, id: string): Promise<boolean>
Remove a route by its
Parameters
- server: string
  Server name
- id: string
  Route
Returns Promise<boolean>
true if route was found and removed, false otherwise

Id
Id
to remove
- Defined in src/caddy/client.ts:499

removeRoutesByHost

removeRoutesByHost(hostname: string, server?: string): Promise<number>
Remove routes matching a hostname
Parameters
- hostname: string
  Hostname to match
- server: string = "https_server"
  Server name
Returns Promise<number>
Number of routes removed
- Defined in src/caddy/client.ts:314

replaceRouteById

replaceRouteById(
    server: string,
    id: string,
    newRoute: CaddyRoute,
): Promise<boolean>
Replace a route by its
Parameters
- server: string
  Server name
- id: string
  Route
- newRoute: CaddyRoute
  New route configuration
Returns Promise<boolean>
true if route was found and replaced, false otherwise

Id
Id
to replace
- Defined in src/caddy/client.ts:464

request

request(path: string, options?: RequestInit): Promise<Response>
Make an HTTP request to Caddy Admin API with timeout
Parameters
- path: string
  API endpoint path
- options: RequestInit = {}
  Fetch options
Returns Promise<Response>
Response object

Throws
NetworkError, TimeoutError, CaddyApiError
- Defined in src/caddy/client.ts:66

stop

stop(): Promise<void>
Gracefully stop the Caddy server This triggers a graceful shutdown, allowing active connections to complete.

Returns Promise<void>
Throws
If Caddy API returns an error response

Throws
If unable to connect to Caddy Admin API

Throws
If the request times out
- Defined in src/caddy/client.ts:529

Class CaddyClient

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CaddyClient

Throws

Methods

adapt

Parameters

Returns Promise<Config & Record<string, unknown>>

Throws

Throws

Throws

Throws

addRoute

Parameters

Returns Promise<boolean>

Throws

Throws

Throws

Throws

addRoutes

Parameters

Returns Promise<{ added: number; skipped: number }>

Throws

Throws

Throws

Throws

Example

applyConfig

Parameters

Returns Promise<void>

Throws

Throws

Throws

Throws

Example

getConfig

Returns Promise<Config & Record<string, unknown>>

Throws

Throws

Throws

getRoutes

Parameters

Returns Promise<CaddyRoute[]>

Throws

Throws

Throws

getServerConfig

Parameters

Returns Promise<Server & Record<string, unknown>>

Throws

Throws

Throws

getServers

Returns Promise<Record<string, Server & Record<string, unknown>>>

Throws

Throws

Throws

getUpstreams

Returns Promise<UpstreamStatus[]>

Throws

Throws

Throws

getVersion

Returns Promise<{ version?: string } & Record<string, unknown>>

insertRoute

Parameters

Returns Promise<void>

patchRoutes

Parameters

Returns Promise<void>

Throws

Throws

Throws

Throws

patchServer