Registering a Server with the AI DBA Workbench API

# httpx, an HTTP client with a requests-like interface.
httpx>=0.28,<1

{
  "name": "register_server",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/main.js"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.9.0"
  }
}

<dependencies>
  <!-- Jackson, for JSON; the HTTP client is part of the JDK. -->
  <dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>3.2.4</version>
  </dependency>
</dependencies>

<!-- The program uses only HttpClient and System.Text.Json, which are
     part of .NET, so it needs no packages. -->

// The program uses only the Go standard library, so it needs no modules.
go 1.25.0

[dependencies]
# The blocking client of reqwest, with rustls for TLS and JSON bodies.
reqwest = { version = "0.13", default-features = false, features = ["blocking", "json", "rustls"] }
serde_json = "1"

source "https://rubygems.org"

# The program uses only Net::HTTP and JSON, which come with Ruby, so it
# needs no gems.

import os
import sys

import httpx

// The program needs no imports: fetch and process are built in to Node.js.

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpTimeoutException;
import java.time.Duration;
import java.util.Map;
import java.util.Objects;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import tools.jackson.core.JacksonException;
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.node.ObjectNode;

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Text.RegularExpressions;

import (
    "bytes"
    "encoding/json"
    "errors"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

use std::env;
use std::error::Error;
use std::process::ExitCode;
use std::sync::LazyLock;
use std::time::Duration;

use reqwest::blocking::{Client, Response};
use reqwest::Method;
use serde_json::{json, Value};

require "json"
require "net/http"

# Stop at the first failing command, treat an unset variable as an error,
# and fail a pipeline when any command in it fails.
set -euo pipefail

# The script needs curl to make the requests and jq to read the replies.
for tool in curl jq; do
    command -v "$tool" >/dev/null || { echo "$tool is required" >&2; exit 1; }
done

SERVER_NAME = "cookbook-register-server"


def settings() -> dict:
    """Reads the settings from the environment.

    The or operator treats an empty variable as unset.
    """
    username = os.environ.get("WORKBENCH_USERNAME") or ""
    password = os.environ.get("WORKBENCH_PASSWORD") or ""
    connection_id = os.environ.get("WORKBENCH_CONNECTION_ID") or ""
    if not (username and password and connection_id):
        raise RuntimeError(
            "WORKBENCH_USERNAME, WORKBENCH_PASSWORD, and "
            "WORKBENCH_CONNECTION_ID must be set"
        )
    return {
        "base_url": (
            os.environ.get("WORKBENCH_URL") or "http://localhost:8080"
        ).rstrip("/"),
        "username": username,
        "password": password,
        "connection_id": connection_id,
        # The Workbench refuses to register a server without a password,
        # even one that uses trust authentication, so fall back to a
        # placeholder.
        "server_password": (
            os.environ.get("PGPASSWORD") or "unused-with-trust-authentication"
        ),
    }

const SERVER_NAME = "cookbook-register-server";

interface Settings {
  baseUrl: string;
  username: string;
  password: string;
  connectionId: string;
  serverPassword: string;
}

// Read the settings from the environment. The || operator, unlike ??, also
// treats an empty variable as unset.
function settings(): Settings {
  const username = process.env.WORKBENCH_USERNAME || "";
  const password = process.env.WORKBENCH_PASSWORD || "";
  const connectionId = process.env.WORKBENCH_CONNECTION_ID || "";
  if (!username || !password || !connectionId) {
    throw new Error(
      "WORKBENCH_USERNAME, WORKBENCH_PASSWORD, and WORKBENCH_CONNECTION_ID " +
        "must be set",
    );
  }
  const baseUrl = process.env.WORKBENCH_URL || "http://localhost:8080";
  return {
    baseUrl: baseUrl.replace(/\/+$/, ""),
    username,
    password,
    connectionId,
    // The Workbench refuses to register a server without a password, even
    // one that uses trust authentication, so fall back to a placeholder.
    serverPassword:
      process.env.PGPASSWORD || "unused-with-trust-authentication",
  };
}

static final String SERVER_NAME = "cookbook-register-server";

/** The settings that the program reads from the environment. */
record Settings(String baseUrl, String username, String password,
        String connectionId, String serverPassword) {}

/**
 * Returns the value of an environment variable, or the fallback if the
 * variable is unset or empty, as an unset variable would be.
 */
static String envOr(String name, String fallback) {
    String value = System.getenv(name);
    return (value != null && !value.isEmpty()) ? value : fallback;
}

/** Reads the settings from the environment. */
static Settings settings() throws IOException {
    String username = envOr("WORKBENCH_USERNAME", "");
    String password = envOr("WORKBENCH_PASSWORD", "");
    String connectionId = envOr("WORKBENCH_CONNECTION_ID", "");
    if (username.isEmpty() || password.isEmpty()
            || connectionId.isEmpty()) {
        throw new IOException("WORKBENCH_USERNAME, WORKBENCH_PASSWORD, "
                + "and WORKBENCH_CONNECTION_ID must be set");
    }
    String baseUrl = envOr("WORKBENCH_URL", "http://localhost:8080")
            .replaceAll("/+$", "");
    // The Workbench refuses to register a server without a password,
    // even one that uses trust authentication, so fall back to a
    // placeholder.
    String serverPassword =
            envOr("PGPASSWORD", "unused-with-trust-authentication");
    return new Settings(baseUrl, username, password, connectionId,
            serverPassword);
}

const string ServerName = "cookbook-register-server";

// Returns the value of an environment variable, or null if the variable
// is unset or empty, as an unset variable would be.
static string? EnvValue(string name) =>
    Environment.GetEnvironmentVariable(name) is { Length: > 0 } value
        ? value
        : null;

// Reads the settings from the environment.
static (string BaseUrl, string Username, string Password,
    string ConnectionId, string ServerPassword) Settings()
{
    var username = EnvValue("WORKBENCH_USERNAME");
    var password = EnvValue("WORKBENCH_PASSWORD");
    var connectionId = EnvValue("WORKBENCH_CONNECTION_ID");
    if (username is null || password is null || connectionId is null)
    {
        throw new InvalidOperationException(
            "WORKBENCH_USERNAME, WORKBENCH_PASSWORD, and "
            + "WORKBENCH_CONNECTION_ID must be set");
    }
    var baseUrl = EnvValue("WORKBENCH_URL") ?? "http://localhost:8080";
    // The Workbench refuses to register a server without a password, even
    // one that uses trust authentication, so fall back to a placeholder.
    var serverPassword =
        EnvValue("PGPASSWORD") ?? "unused-with-trust-authentication";
    return (baseUrl.TrimEnd('/'), username, password, connectionId,
        serverPassword);
}

const serverName = "cookbook-register-server"

// settings holds the values that the program reads from the environment.
type settings struct {
    baseURL        string
    username       string
    password       string
    connectionID   string
    serverPassword string
}

// envOr returns the value of an environment variable, or the fallback if
// the variable is unset or empty, as an unset variable would be.
func envOr(name, fallback string) string {
    if value := os.Getenv(name); value != "" {
        return value
    }
    return fallback
}

// loadSettings reads the settings from the environment.
func loadSettings() (settings, error) {
    s := settings{
        baseURL:      strings.TrimRight(envOr("WORKBENCH_URL", "http://localhost:8080"), "/"),
        username:     os.Getenv("WORKBENCH_USERNAME"),
        password:     os.Getenv("WORKBENCH_PASSWORD"),
        connectionID: os.Getenv("WORKBENCH_CONNECTION_ID"),
        // The Workbench refuses to register a server without a password,
        // even one that uses trust authentication, so fall back to a
        // placeholder.
        serverPassword: envOr("PGPASSWORD", "unused-with-trust-authentication"),
    }
    if s.username == "" || s.password == "" || s.connectionID == "" {
        return s, errors.New("WORKBENCH_USERNAME, WORKBENCH_PASSWORD, and WORKBENCH_CONNECTION_ID must be set")
    }
    return s, nil
}

const SERVER_NAME: &str = "cookbook-register-server";

/// Any error, boxed, so that a function can return errors of several types
/// with the ? operator.
type Result<T> = std::result::Result<T, Box<dyn Error>>;

/// The settings that the program reads from the environment.
struct Settings {
    base_url: String,
    username: String,
    password: String,
    connection_id: String,
    server_password: String,
}

/// Returns the value of an environment variable, if it is set and not
/// empty; an empty variable counts as unset.
fn env_value(name: &str) -> Option<String> {
    env::var(name).ok().filter(|value| !value.is_empty())
}

/// Reads the settings from the environment.
fn settings() -> Result<Settings> {
    let (Some(username), Some(password), Some(connection_id)) = (
        env_value("WORKBENCH_USERNAME"),
        env_value("WORKBENCH_PASSWORD"),
        env_value("WORKBENCH_CONNECTION_ID"),
    ) else {
        return Err("WORKBENCH_USERNAME, WORKBENCH_PASSWORD, and \
                    WORKBENCH_CONNECTION_ID must be set"
            .into());
    };
    let base_url = env_value("WORKBENCH_URL")
        .unwrap_or_else(|| "http://localhost:8080".to_string())
        .trim_end_matches('/')
        .to_string();
    // The Workbench refuses to register a server without a password, even
    // one that uses trust authentication, so fall back to a placeholder.
    let server_password =
        env_value("PGPASSWORD").unwrap_or_else(|| "unused-with-trust-authentication".to_string());
    Ok(Settings {
        base_url,
        username,
        password,
        connection_id,
        server_password,
    })
}

SERVER_NAME = "cookbook-register-server"

# Returns the value of an environment variable, or a fallback if the
# variable is unset or empty, as an unset variable would be.
def env_or(name, fallback)
  value = ENV[name]
  value.nil? || value.empty? ? fallback : value
end

# Reads the settings from the environment.
def settings
  username = env_or("WORKBENCH_USERNAME", nil)
  password = env_or("WORKBENCH_PASSWORD", nil)
  connection_id = env_or("WORKBENCH_CONNECTION_ID", nil)
  unless username && password && connection_id
    raise "WORKBENCH_USERNAME, WORKBENCH_PASSWORD, and " \
          "WORKBENCH_CONNECTION_ID must be set"
  end

  {
    base_url: env_or("WORKBENCH_URL", "http://localhost:8080").sub(%r{/+\z}, ""),
    username: username,
    password: password,
    connection_id: connection_id,
    # The Workbench refuses to register a server without a password, even
    # one that uses trust authentication, so fall back to a placeholder.
    server_password: env_or("PGPASSWORD", "unused-with-trust-authentication")
  }
end

# Read the settings from the environment. The :- and :? forms, unlike - and
# ?, treat an empty variable as unset.
WORKBENCH_URL="${WORKBENCH_URL:-http://localhost:8080}"
WORKBENCH_URL="${WORKBENCH_URL%/}"
: "${WORKBENCH_USERNAME:?WORKBENCH_USERNAME must be set}"
: "${WORKBENCH_PASSWORD:?WORKBENCH_PASSWORD must be set}"
: "${WORKBENCH_CONNECTION_ID:?WORKBENCH_CONNECTION_ID must be set}"

# The Workbench refuses to register a server without a password, even one
# that uses trust authentication, so the script falls back to a placeholder.
SERVER_PASSWORD="${PGPASSWORD:-unused-with-trust-authentication}"
SERVER_NAME="cookbook-register-server"

def api(method: str, base_url: str, path: str, token: str | None = None,
        **kwargs) -> httpx.Response:
    """Sends a request to the API and returns the response.

    A request that the server rejects raises an error that includes the
    message from the server, which raise_for_status alone would leave out.
    """
    headers = {"Authorization": f"Bearer {token}"} if token else {}
    response = httpx.request(
        method, f"{base_url}/api/v1{path}", headers=headers, timeout=30,
        **kwargs,
    )
    if response.is_error:
        raise RuntimeError(
            f"{method} {path} failed with status {response.status_code}: "
            f"{response.text.strip()}"
        )
    return response

// Sends a request to the API and returns the response. A request that the
// server rejects throws an error that includes the message from the server.
async function api(
  method: string,
  baseUrl: string,
  path: string,
  token?: string,
  body?: unknown,
): Promise<Response> {
  const headers: Record<string, string> = {};
  if (token) headers["Authorization"] = `Bearer ${token}`;
  if (body !== undefined) headers["Content-Type"] = "application/json";

  const response = await fetch(`${baseUrl}/api/v1${path}`, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(30_000),
  });
  if (!response.ok) {
    const text = (await response.text()).trim();
    throw new Error(
      `${method} ${path} failed with status ${response.status}: ${text}`,
    );
  }
  return response;
}

/** One client serves every request; it is safe to share. */
static final HttpClient CLIENT = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(30))
        .build();

/**
 * Sends a request and returns the response with its whole body. The
 * request timeout stops applying once the headers arrive, so a server
 * that stalls part of the way through the body would hang send(); this
 * applies the same timeout to the whole exchange instead.
 */
static HttpResponse<String> send(HttpRequest request)
        throws IOException, InterruptedException {
    Duration timeout = request.timeout().orElseThrow();
    CompletableFuture<HttpResponse<String>> pending =
            CLIENT.sendAsync(request, HttpResponse.BodyHandlers.ofString());
    try {
        return pending.get(timeout.toMillis(), TimeUnit.MILLISECONDS);
    } catch (TimeoutException e) {
        pending.cancel(true);
        throw new HttpTimeoutException("request timed out");
    } catch (ExecutionException e) {
        if (e.getCause() instanceof IOException cause) {
            throw cause;
        }
        throw new IOException(e.getCause());
    }
}

/** Converts between JSON text and Java objects. */
static final ObjectMapper JSON = new ObjectMapper();

/**
 * Sends a request to the API and returns the response. The token and
 * the body may be null. A request that the server rejects throws an
 * error that includes the message from the server.
 */
static HttpResponse<String> api(String method, String baseUrl,
        String path, String token, Object body)
        throws IOException, InterruptedException {
    HttpRequest.Builder request = HttpRequest
            .newBuilder(URI.create(baseUrl + "/api/v1" + path))
            .timeout(Duration.ofSeconds(30));
    if (token != null) {
        request.header("Authorization", "Bearer " + token);
    }
    HttpRequest.BodyPublisher content = HttpRequest.BodyPublishers.noBody();
    if (body != null) {
        request.header("Content-Type", "application/json");
        content = HttpRequest.BodyPublishers.ofString(
                JSON.writeValueAsString(body));
    }

    HttpResponse<String> response = send(request.method(method, content).build());
    if (response.statusCode() >= 400) {
        throw new IOException(method + " " + path
                + " failed with status " + response.statusCode() + ": "
                + response.body().strip());
    }
    return response;
}

/** Sends a request to the API and returns the JSON reply. */
static JsonNode apiJson(String method, String baseUrl, String path,
        String token, Object body)
        throws IOException, InterruptedException {
    return JSON.readTree(api(method, baseUrl, path, token, body).body());
}

// One client serves every request, with a timeout for each. The handler
// keeps no cookies, so the session token goes only where the program
// sends it.
var http = new HttpClient(new SocketsHttpHandler { UseCookies = false })
{
    Timeout = TimeSpan.FromSeconds(30),
};

// Sends a request to the API and returns the response, which the caller
// must dispose of. A request that the server rejects throws an error that
// includes the message from the server.
async Task<HttpResponseMessage> Api(string method, string baseUrl,
    string path, string? token = null, object? body = null)
{
    using var request = new HttpRequestMessage(
        new HttpMethod(method), $"{baseUrl}/api/v1{path}");
    if (token is not null)
    {
        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", token);
    }
    if (body is not null)
    {
        request.Content = JsonContent.Create(body);
    }

    var response = await http.SendAsync(request);
    var code = (int)response.StatusCode;
    if (code >= 400)
    {
        var text = (await response.Content.ReadAsStringAsync()).Trim();
        response.Dispose();
        throw new HttpRequestException(
            $"{method} {path} failed with status {code}: {text}");
    }
    return response;
}

// Sends a request to the API and returns the JSON reply.
async Task<JsonNode> ApiJson(string method, string baseUrl, string path,
    string? token = null, object? body = null)
{
    using var response = await Api(method, baseUrl, path, token, body);
    return JsonNode.Parse(await response.Content.ReadAsStringAsync())
        ?? throw new InvalidOperationException(
            $"{method} {path} returned no JSON");
}

// client gives every request a timeout; the default client has none.
var client = &http.Client{Timeout: 30 * time.Second}

// api sends a request to the API and returns the response, which the caller
// must close. A request that the server rejects returns an error that
// includes the message from the server.
func api(method, baseURL, path, token string, body any) (*http.Response, error) {
    var reader io.Reader
    if body != nil {
        encoded, err := json.Marshal(body)
        if err != nil {
            return nil, err
        }
        reader = bytes.NewReader(encoded)
    }

    req, err := http.NewRequest(method, baseURL+"/api/v1"+path, reader)
    if err != nil {
        return nil, err
    }
    if body != nil {
        req.Header.Set("Content-Type", "application/json")
    }
    if token != "" {
        req.Header.Set("Authorization", "Bearer "+token)
    }

    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    if resp.StatusCode >= 400 {
        defer resp.Body.Close()
        text, _ := io.ReadAll(resp.Body)
        return nil, fmt.Errorf("%s %s failed with status %d: %s",
            method, path, resp.StatusCode, strings.TrimSpace(string(text)))
    }
    return resp, nil
}

// apiJSON sends a request and decodes the JSON reply into out, if given.
func apiJSON(method, baseURL, path, token string, body, out any) error {
    resp, err := api(method, baseURL, path, token, body)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    if out == nil {
        return nil
    }
    return json.NewDecoder(resp.Body).Decode(out)
}

/// One client serves every request, with a timeout for each; the client
/// has none by default.
static CLIENT: LazyLock<Client> = LazyLock::new(|| {
    Client::builder()
        .timeout(Duration::from_secs(30))
        .build()
        .expect("could not create the HTTP client")
});

/// Sends a request to the API and returns the response. A request that the
/// server rejects returns an error that includes the message from the
/// server.
fn api(
    method: Method,
    base_url: &str,
    path: &str,
    token: Option<&str>,
    body: Option<&Value>,
) -> Result<Response> {
    let mut request = CLIENT.request(method.clone(), format!("{base_url}/api/v1{path}"));
    if let Some(token) = token {
        request = request.bearer_auth(token);
    }
    if let Some(body) = body {
        request = request.json(body);
    }

    let response = request.send()?;
    let status = response.status().as_u16();
    if status >= 400 {
        let text = response.text()?;
        return Err(format!(
            "{method} {path} failed with status {status}: {}",
            text.trim()
        )
        .into());
    }
    Ok(response)
}

# Sends a request to the API and returns the response. The body, if given,
# is sent as JSON. A request that the server rejects raises an error that
# includes the message from the server.
def api(method, base_url, path, token = nil, body = nil)
  uri = URI("#{base_url}/api/v1#{path}")
  headers = {}
  headers["Authorization"] = "Bearer #{token}" if token
  headers["Content-Type"] = "application/json" if body

  # Net::HTTP has no overall timeout, so limit both the connection and
  # each read.
  response = Net::HTTP.start(uri.host, uri.port,
                             use_ssl: uri.scheme == "https",
                             open_timeout: 30, read_timeout: 30) do |http|
    http.send_request(method, uri.request_uri, body&.to_json, headers)
  end
  if response.code.to_i >= 400
    raise "#{method} #{path} failed with status #{response.code}: " \
          "#{response.body.to_s.strip}"
  end
  response
end

# Sends an authenticated request and prints the JSON reply:
# api METHOD PATH TOKEN [curl options]. With --fail-with-body, a request
# that the server rejects leaves the server's error message in the reply,
# and the function prints it to standard error.
# The token goes to curl in a header file that bash supplies through a pipe,
# so that it never appears in the arguments of the curl process, which other
# users can read in the process list.
api() {
    local method="$1" path="$2" token="$3"
    shift 3
    local response
    response=$(curl --silent --show-error --fail-with-body \
        --connect-timeout 10 --max-time 30 \
        --request "$method" \
        --header @<(printf 'Authorization: Bearer %s\n' "$token") \
        "$@" "$WORKBENCH_URL/api/v1$path") || {
        echo "$method $path failed: $response" >&2
        return 1
    }
    printf '%s' "$response"
}

def login(base_url: str, username: str, password: str) -> str:
    """Logs in and returns the session token.

    The server returns the token in a session_token cookie, not in the
    body of the reply.
    """
    response = api("POST", base_url, "/auth/login",
                   json={"username": username, "password": password})
    token = response.cookies.get("session_token")
    if not token:
        raise RuntimeError("The login reply had no session_token cookie")
    return token

// Logs in and returns the session token. The server returns the token in a
// session_token cookie, not in the body of the reply.
async function login(
  baseUrl: string,
  username: string,
  password: string,
): Promise<string> {
  const response = await api("POST", baseUrl, "/auth/login", undefined, {
    username,
    password,
  });
  for (const cookie of response.headers.getSetCookie()) {
    const match = /^session_token=([^;]*)/.exec(cookie);
    if (match) return match[1];
  }
  throw new Error("The login reply had no session_token cookie");
}

/** Matches the session_token cookie in a Set-Cookie header. */
static final Pattern SESSION_COOKIE =
        Pattern.compile("^session_token=([^;]*)");

/**
 * Logs in and returns the session token. The server returns the token
 * in a session_token cookie, not in the body of the reply.
 */
static String login(String baseUrl, String username, String password)
        throws IOException, InterruptedException {
    HttpResponse<String> response = api("POST", baseUrl, "/auth/login",
            null, Map.of("username", username, "password", password));
    for (String cookie : response.headers().allValues("Set-Cookie")) {
        Matcher match = SESSION_COOKIE.matcher(cookie);
        if (match.find()) {
            return match.group(1);
        }
    }
    throw new IOException("The login reply had no session_token cookie");
}

// Logs in and returns the session token. The server returns the token in a
// session_token cookie, not in the body of the reply.
async Task<string> Login(string baseUrl, string username, string password)
{
    using var response = await Api("POST", baseUrl, "/auth/login",
        body: new { username, password });
    if (response.Headers.TryGetValues("Set-Cookie", out var cookies))
    {
        foreach (var cookie in cookies)
        {
            var match = Regex.Match(cookie, "^session_token=([^;]*)");
            if (match.Success)
            {
                return match.Groups[1].Value;
            }
        }
    }
    throw new InvalidOperationException(
        "The login reply had no session_token cookie");
}

// login logs in and returns the session token. The server returns the token
// in a session_token cookie, not in the body of the reply.
func login(baseURL, username, password string) (string, error) {
    resp, err := api("POST", baseURL, "/auth/login", "", map[string]string{
        "username": username,
        "password": password,
    })
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    for _, cookie := range resp.Cookies() {
        if cookie.Name == "session_token" {
            return cookie.Value, nil
        }
    }
    return "", errors.New("the login reply had no session_token cookie")
}

/// Logs in and returns the session token. The server returns the token in
/// a session_token cookie, not in the body of the reply.
fn login(base_url: &str, username: &str, password: &str) -> Result<String> {
    let body = json!({ "username": username, "password": password });
    let response = api(Method::POST, base_url, "/auth/login", None, Some(&body))?;
    for cookie in response.headers().get_all("set-cookie") {
        if let Some(rest) = cookie.to_str()?.strip_prefix("session_token=") {
            // The value runs up to the first attribute, if there is one.
            let value = rest.split(';').next().unwrap_or_default();
            return Ok(value.to_string());
        }
    }
    Err("the login reply had no session_token cookie".into())
}

# Logs in and returns the session token. The server returns the token in a
# session_token cookie, not in the body of the reply.
def login(base_url, username, password)
  response = api("POST", base_url, "/auth/login", nil,
                 { username: username, password: password })
  (response.get_fields("set-cookie") || []).each do |cookie|
    match = /\Asession_token=([^;]*)/.match(cookie)
    return match[1] if match
  end
  raise "The login reply had no session_token cookie"
end

# Logs in and prints the session token. The server returns the token in a
# session_token cookie, so the request includes the response headers.
login() {
    local response
    # jq reads the credentials from its environment, and curl reads the
    # request from standard input, so that neither the password nor the
    # request body appears in a process list.
    response=$(jq -n '{username: env.WORKBENCH_USERNAME,
                       password: env.WORKBENCH_PASSWORD}' |
        curl --silent --show-error --fail-with-body --include \
             --connect-timeout 10 --max-time 30 \
             --request POST \
             --header 'Content-Type: application/json' \
             --data @- \
             "$WORKBENCH_URL/api/v1/auth/login") || {
        echo "Login failed: $response" >&2
        return 1
    }

    # Header lines end in a carriage return, which tr removes.
    local token
    token=$(printf '%s' "$response" | tr -d '\r' |
        sed -n 's/^[Ss]et-[Cc]ookie: session_token=\([^;]*\).*/\1/p')
    if [[ -z "$token" ]]; then
        echo "The login reply had no session_token cookie" >&2
        return 1
    fi
    printf '%s' "$token"
}

def get_connection(base_url: str, session: str, connection_id: str) -> dict:
    """Returns the details of an existing connection, which the program
    uses as the address of the server to register."""
    return api("GET", base_url, f"/connections/{connection_id}",
               session).json()

interface Connection {
  id: number;
  name: string;
  host: string;
  port: number;
  database_name: string;
  username: string;
  ssl_mode?: string;
  is_monitored: boolean;
}

// Returns the details of an existing connection, which the program uses as
// the address of the server to register.
async function getConnection(
  baseUrl: string,
  session: string,
  connectionId: string,
): Promise<Connection> {
  const response = await api(
    "GET",
    baseUrl,
    `/connections/${connectionId}`,
    session,
  );
  return (await response.json()) as Connection;
}

/**
 * Returns the details of an existing connection, which the program
 * uses as the address of the server to register.
 */
static JsonNode getConnection(String baseUrl, String session,
        String connectionId) throws IOException, InterruptedException {
    return apiJson("GET", baseUrl, "/connections/" + connectionId,
            session, null);
}

// Returns the details of an existing connection, which the program uses
// as the address of the server to register.
async Task<JsonNode> GetConnection(string baseUrl, string session,
    string connectionId) =>
    await ApiJson("GET", baseUrl, $"/connections/{connectionId}", session);

// connection is the part of a connection that the program needs.
type connection struct {
    ID           int64  `json:"id"`
    Name         string `json:"name"`
    Host         string `json:"host"`
    Port         int    `json:"port"`
    DatabaseName string `json:"database_name"`
    Username     string `json:"username"`
    SSLMode      string `json:"ssl_mode"`
    IsMonitored  bool   `json:"is_monitored"`
}

// getConnection returns the details of an existing connection, which the
// program uses as the address of the server to register.
func getConnection(baseURL, session, id string) (connection, error) {
    var c connection
    err := apiJSON("GET", baseURL, "/connections/"+id, session, nil, &c)
    return c, err
}

/// Returns the details of an existing connection, which the program uses
/// as the address of the server to register.
fn get_connection(base_url: &str, session: &str, connection_id: &str) -> Result<Value> {
    let path = format!("/connections/{connection_id}");
    Ok(api(Method::GET, base_url, &path, Some(session), None)?.json()?)
}

# Returns the details of an existing connection, which the program uses as
# the address of the server to register.
def get_connection(base_url, session, connection_id)
  JSON.parse(api("GET", base_url, "/connections/#{connection_id}",
                 session).body)
end

# Prints the details of an existing connection, which the script uses as
# the address of the server to register.
get_connection() {
    local session="$1" connection_id="$2"
    api GET "/connections/$connection_id" "$session"
}

def register_server(base_url: str, session: str, name: str, template: dict,
                    password: str) -> int:
    """Registers a server and returns the ID of the new connection.

    The address comes from an existing connection. The request must
    include a password, and a description, which the server needs in
    version 1.0.0.
    """
    created = api("POST", base_url, "/connections", session, json={
        "name": name,
        "description": "Registered by the cookbook",
        "host": template["host"],
        "port": template["port"],
        "database_name": template["database_name"],
        "username": template["username"],
        "ssl_mode": template.get("ssl_mode"),
        "password": password,
        "is_monitored": True,
        "is_shared": False,
    }).json()
    return created["id"]

// Registers a server and returns the ID of the new connection. The address
// comes from an existing connection. The request must include a password,
// and a description, which the server needs in version 1.0.0.
async function registerServer(
  baseUrl: string,
  session: string,
  name: string,
  template: Connection,
  password: string,
): Promise<number> {
  const response = await api("POST", baseUrl, "/connections", session, {
    name,
    description: "Registered by the cookbook",
    host: template.host,
    port: template.port,
    database_name: template.database_name,
    username: template.username,
    ssl_mode: template.ssl_mode,
    password,
    is_monitored: true,
    is_shared: false,
  });
  return ((await response.json()) as Connection).id;
}

/**
 * Registers a server and returns the ID of the new connection. The
 * address comes from an existing connection. The request must include
 * a password, and a description, which the server needs in version
 * 1.0.0.
 */
static long registerServer(String baseUrl, String session, String name,
        JsonNode template, String password)
        throws IOException, InterruptedException {
    ObjectNode body = JSON.createObjectNode()
            .put("name", name)
            .put("description", "Registered by the cookbook");
    // Copy the address from the existing connection; set() writes a
    // JSON null for a field that the connection lacks.
    for (String field : new String[] {
            "host", "port", "database_name", "username", "ssl_mode"}) {
        body.set(field, template.get(field));
    }
    body.put("password", password)
            .put("is_monitored", true)
            .put("is_shared", false);

    JsonNode created = apiJson("POST", baseUrl, "/connections", session,
            body);
    return created.get("id").asLong();
}

// Registers a server and returns the ID of the new connection. The address
// comes from an existing connection. The request must include a password,
// and a description, which the server needs in version 1.0.0.
async Task<long> RegisterServer(string baseUrl, string session,
    string name, JsonNode template, string password)
{
    // A JSON node belongs to one parent at a time, so the program copies
    // each field that it takes from the existing connection.
    var body = new JsonObject
    {
        ["name"] = name,
        ["description"] = "Registered by the cookbook",
        ["host"] = template["host"]?.DeepClone(),
        ["port"] = template["port"]?.DeepClone(),
        ["database_name"] = template["database_name"]?.DeepClone(),
        ["username"] = template["username"]?.DeepClone(),
        ["ssl_mode"] = template["ssl_mode"]?.DeepClone(),
        ["password"] = password,
        ["is_monitored"] = true,
        ["is_shared"] = false,
    };
    var created = await ApiJson("POST", baseUrl, "/connections", session,
        body);
    return created["id"]!.GetValue<long>();
}

// registerServer registers a server and returns the ID of the new
// connection. The address comes from an existing connection. The request
// must include a password, and a description, which the server needs in
// version 1.0.0.
func registerServer(baseURL, session, name string, template connection, password string) (int64, error) {
    var created connection
    err := apiJSON("POST", baseURL, "/connections", session, map[string]any{
        "name":          name,
        "description":   "Registered by the cookbook",
        "host":          template.Host,
        "port":          template.Port,
        "database_name": template.DatabaseName,
        "username":      template.Username,
        "ssl_mode":      template.SSLMode,
        "password":      password,
        "is_monitored":  true,
        "is_shared":     false,
    }, &created)
    return created.ID, err
}

/// Registers a server and returns the ID of the new connection. The
/// address comes from an existing connection. The request must include a
/// password, and a description, which the server needs in version 1.0.0.
fn register_server(
    base_url: &str,
    session: &str,
    name: &str,
    template: &Value,
    password: &str,
) -> Result<i64> {
    // Indexing a missing field gives null rather than a panic.
    let body = json!({
        "name": name,
        "description": "Registered by the cookbook",
        "host": template["host"],
        "port": template["port"],
        "database_name": template["database_name"],
        "username": template["username"],
        "ssl_mode": template["ssl_mode"],
        "password": password,
        "is_monitored": true,
        "is_shared": false,
    });
    let created: Value = api(
        Method::POST,
        base_url,
        "/connections",
        Some(session),
        Some(&body),
    )?
    .json()?;
    Ok(created["id"]
        .as_i64()
        .ok_or("the reply had no connection ID")?)
}

# Registers a server and returns the ID of the new connection. The address
# comes from an existing connection. The request must include a password,
# and a description, which the server needs in version 1.0.0.
def register_server(base_url, session, name, template, password)
  response = api("POST", base_url, "/connections", session, {
                   name: name,
                   description: "Registered by the cookbook",
                   host: template.fetch("host"),
                   port: template.fetch("port"),
                   database_name: template.fetch("database_name"),
                   username: template.fetch("username"),
                   ssl_mode: template["ssl_mode"],
                   password: password,
                   is_monitored: true,
                   is_shared: false
                 })
  JSON.parse(response.body).fetch("id")
end

# Registers a server and prints the ID of the new connection. The address
# comes from an existing connection, given as JSON in the third argument.
register_server() {
    local session="$1" name="$2" template="$3"
    # The template's host, port, database, and user become the new
    # connection's. jq reads the password from its environment, which keeps
    # it off the command line, and the request sends a description, which
    # the server needs in version 1.0.0.
    SERVER_PASSWORD="$SERVER_PASSWORD" \
    jq --arg name "$name" \
       '{name: $name, description: "Registered by the cookbook",
         host, port, database_name, username, ssl_mode,
         password: env.SERVER_PASSWORD, is_monitored: true,
         is_shared: false}' \
       <<<"$template" |
        api POST /connections "$session" \
            --header 'Content-Type: application/json' --data @- |
        jq -r '.id'
}

def find_connection(base_url: str, session: str, name: str) -> dict | None:
    """Returns the named connection from the list, or None if the list has
    no such connection."""
    connections = api("GET", base_url, "/connections", session).json()
    return next((c for c in connections if c["name"] == name), None)

// Returns the named connection from the list, or undefined if the list has
// no such connection.
async function findConnection(
  baseUrl: string,
  session: string,
  name: string,
): Promise<Connection | undefined> {
  const response = await api("GET", baseUrl, "/connections", session);
  const connections = (await response.json()) as Connection[];
  return connections.find((c) => c.name === name);
}

/**
 * Returns the named connection from the list, or null if the list has
 * no such connection.
 */
static JsonNode findConnection(String baseUrl, String session,
        String name) throws IOException, InterruptedException {
    for (JsonNode connection
            : apiJson("GET", baseUrl, "/connections", session, null)) {
        if (name.equals(connection.get("name").asString())) {
            return connection;
        }
    }
    return null;
}

// Returns the named connection from the list, or null if the list has no
// such connection.
async Task<JsonNode?> FindConnection(string baseUrl, string session,
    string name)
{
    var connections = await ApiJson("GET", baseUrl, "/connections", session);
    return connections.AsArray().FirstOrDefault(
        c => c?["name"]?.GetValue<string>() == name);
}

// findConnection returns the named connection from the list, or nil if the
// list has no such connection.
func findConnection(baseURL, session, name string) (*connection, error) {
    var connections []connection
    if err := apiJSON("GET", baseURL, "/connections", session, nil, &connections); err != nil {
        return nil, err
    }
    for i := range connections {
        if connections[i].Name == name {
            return &connections[i], nil
        }
    }
    return nil, nil
}

/// Returns the named connection from the list, or None if the list has no
/// such connection.
fn find_connection(base_url: &str, session: &str, name: &str) -> Result<Option<Value>> {
    let connections: Vec<Value> =
        api(Method::GET, base_url, "/connections", Some(session), None)?.json()?;
    Ok(connections.into_iter().find(|c| c["name"] == name))
}