maggesandClaude Sonnet 5
e2fefcdf9c
- versions.env pins podman, conmon, crun, netavark, aardvark-dns, passt, and fuse-overlayfs to verified upstream source checksums; SlackBuild recipes, scripts/build-packages.sh, checksums.sh, release.sh, and update-versions.sh implement the reproducible pipeline; GitHub Actions workflows build in a Slackware container and publish releases without committing any binaries. - plugin/podman.plg installs/updates/removes all eight packages (the seven components plus the plugin's own unraid-podman scaffolding package) via upgradepkg, using the official Unraid array-event hook mechanism (event/disks_mounted, event/stopping) instead of editing /boot/config/go. rc.podman and the sbin/ helper scripts implement storage creation, config seeding/sync, preflight checks, autostart with per-container Safe-Mode, and package verify/update/rollback. - webui/plugins/podman implements the Dashboard, Containers, Pods, Images, Volumes, Networks, Logs, Terminal, Compose, and Settings panels against the approved mockup (webui/mockups/prototype.html), talking to podman system service exclusively via PodmanClient.php (libpod REST API over the Unix socket), with two documented exceptions: Terminal's one-shot exec model and Compose's use of the podman compose CLI, since libpod has no REST equivalent for either. - docs/ARCHITECTURE.md and docs/ROADMAP.md record the design decisions and honest current status (syntax-checked, unit- and integration-tested against fake sockets/servers; not yet run against a real Unraid/Podman/Slackware system). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
405 lines
15 KiB
PHP
405 lines
15 KiB
PHP
<?php
|
|
/**
|
|
* PodmanClient.php
|
|
*
|
|
* Thin PHP client for the Podman libpod REST API, spoken exclusively over
|
|
* the local Unix socket that plugin/rc.d/rc.podman starts
|
|
* (`podman system service`, see docs/ARCHITECTURE.md section 18.1). Every
|
|
* AJAX endpoint under webui/plugins/podman/ajax/ goes through this class —
|
|
* none of them shell out to the `podman` binary. The one deliberate,
|
|
* documented exception to "talk to the API, not the CLI" is Compose
|
|
* support (see ajax/compose.php), because compose has no REST equivalent
|
|
* in libpod at all, not because it was more convenient to shell out.
|
|
*
|
|
* Design notes:
|
|
* - One cURL handle per request (kept simple; this is a low-traffic
|
|
* admin UI, not a high-throughput proxy — a persistent handle pool
|
|
* would be premature).
|
|
* - Every method returns a plain PHP array/bool decoded from the API's
|
|
* JSON response, or throws PodmanApiException on a non-2xx response
|
|
* or transport failure, so callers can use a single try/catch instead
|
|
* of checking a mixed-shape return value after every call.
|
|
* - No business logic lives here — this class only knows how to speak
|
|
* the libpod API. Formatting, filtering, and aggregation belong in the
|
|
* ajax/*.php endpoints that use it (see e.g. ajax/system.php for
|
|
* dashboard aggregation).
|
|
*/
|
|
|
|
declare(strict_types=1);
|
|
|
|
final class PodmanApiException extends \RuntimeException
|
|
{
|
|
public int $httpStatus;
|
|
|
|
public function __construct(string $message, int $httpStatus = 0, ?\Throwable $previous = null)
|
|
{
|
|
parent::__construct($message, 0, $previous);
|
|
$this->httpStatus = $httpStatus;
|
|
}
|
|
}
|
|
|
|
final class PodmanClient
|
|
{
|
|
/** libpod REST API version this client targets. */
|
|
private const API_VERSION = 'v4.0.0';
|
|
|
|
private string $socketPath;
|
|
private int $timeoutSeconds;
|
|
|
|
public function __construct(string $socketPath, int $timeoutSeconds = 15)
|
|
{
|
|
$this->socketPath = $socketPath;
|
|
$this->timeoutSeconds = $timeoutSeconds;
|
|
}
|
|
|
|
// -------------------------------------------------------------------
|
|
// System
|
|
// -------------------------------------------------------------------
|
|
|
|
/** GET /info — engine + host information (used by the Dashboard/Settings panels). */
|
|
public function info(): array
|
|
{
|
|
return $this->request('GET', '/info');
|
|
}
|
|
|
|
/** GET /system/df — image/container/volume disk usage summary. */
|
|
public function systemDf(): array
|
|
{
|
|
return $this->request('GET', '/system/df');
|
|
}
|
|
|
|
/** Quick reachability check — used by ajax/system.php's status endpoint. */
|
|
public function ping(): bool
|
|
{
|
|
try {
|
|
$this->request('GET', '/_ping', [], true);
|
|
return true;
|
|
} catch (PodmanApiException $e) {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
// -------------------------------------------------------------------
|
|
// Containers
|
|
// -------------------------------------------------------------------
|
|
|
|
/** GET /containers/json — list containers. $all=true includes stopped ones. */
|
|
public function listContainers(bool $all = true): array
|
|
{
|
|
return $this->request('GET', '/containers/json', ['all' => $all ? 'true' : 'false']);
|
|
}
|
|
|
|
/** GET /containers/{id}/json — full inspect data for one container. */
|
|
public function inspectContainer(string $id): array
|
|
{
|
|
return $this->request('GET', '/containers/' . rawurlencode($id) . '/json');
|
|
}
|
|
|
|
/** GET /containers/{id}/stats?stream=false — one-shot CPU/memory snapshot. */
|
|
public function containerStats(string $id): array
|
|
{
|
|
return $this->request('GET', '/containers/' . rawurlencode($id) . '/stats', ['stream' => 'false']);
|
|
}
|
|
|
|
public function startContainer(string $id): void
|
|
{
|
|
$this->request('POST', '/containers/' . rawurlencode($id) . '/start', [], true);
|
|
}
|
|
|
|
public function stopContainer(string $id, int $timeoutSeconds = 10): void
|
|
{
|
|
$this->request('POST', '/containers/' . rawurlencode($id) . '/stop', ['t' => (string) $timeoutSeconds], true);
|
|
}
|
|
|
|
public function restartContainer(string $id, int $timeoutSeconds = 10): void
|
|
{
|
|
$this->request('POST', '/containers/' . rawurlencode($id) . '/restart', ['t' => (string) $timeoutSeconds], true);
|
|
}
|
|
|
|
public function removeContainer(string $id, bool $force = false): void
|
|
{
|
|
$this->request('DELETE', '/containers/' . rawurlencode($id), ['force' => $force ? 'true' : 'false'], true);
|
|
}
|
|
|
|
/**
|
|
* GET /containers/{id}/logs — returns the raw (already de-multiplexed
|
|
* where possible) log text. Podman's non-TTY log stream uses the same
|
|
* 8-byte-frame-header multiplexing as `attach`; we strip those frame
|
|
* headers in demuxStream() so callers just get plain text lines.
|
|
*/
|
|
public function containerLogs(string $id, int $tail = 200, bool $timestamps = true): string
|
|
{
|
|
$query = [
|
|
'stdout' => 'true',
|
|
'stderr' => 'true',
|
|
'tail' => (string) $tail,
|
|
'timestamps' => $timestamps ? 'true' : 'false',
|
|
];
|
|
$raw = $this->requestRaw('GET', '/containers/' . rawurlencode($id) . '/logs', $query);
|
|
return self::demuxStream($raw);
|
|
}
|
|
|
|
// -------------------------------------------------------------------
|
|
// Exec — see webui/plugins/podman/ajax/exec.php for the important
|
|
// caveat: this implements one-shot "run a command, return its output"
|
|
// semantics over the exec API, not a true interactive PTY (which would
|
|
// require a persistent bidirectional connection this stack doesn't
|
|
// have — see that file's header comment for the full explanation).
|
|
// -------------------------------------------------------------------
|
|
|
|
/**
|
|
* Creates and immediately runs one command inside a container via the
|
|
* real libpod exec API (POST /containers/{id}/exec, then
|
|
* POST /exec/{id}/start) and returns its combined stdout+stderr output.
|
|
* Tty=true is used deliberately so the response is a plain byte stream
|
|
* with no frame-header demultiplexing needed (see containerLogs() for
|
|
* the non-TTY case, which does need it).
|
|
*/
|
|
public function execRun(string $containerId, array $cmd, string $workingDir = ''): string
|
|
{
|
|
$createBody = [
|
|
'AttachStdin' => false,
|
|
'AttachStdout' => true,
|
|
'AttachStderr' => true,
|
|
'Tty' => true,
|
|
'Cmd' => $cmd,
|
|
];
|
|
if ($workingDir !== '') {
|
|
$createBody['WorkingDir'] = $workingDir;
|
|
}
|
|
|
|
$created = $this->request('POST', '/containers/' . rawurlencode($containerId) . '/exec', [], false, $createBody);
|
|
$execId = $created['Id'] ?? null;
|
|
if (!is_string($execId) || $execId === '') {
|
|
throw new PodmanApiException('exec create response did not include an Id');
|
|
}
|
|
|
|
$output = $this->requestRaw('POST', '/exec/' . rawurlencode($execId) . '/start', [], [
|
|
'Detach' => false,
|
|
'Tty' => true,
|
|
]);
|
|
|
|
return $output;
|
|
}
|
|
|
|
// -------------------------------------------------------------------
|
|
// Pods
|
|
// -------------------------------------------------------------------
|
|
|
|
public function listPods(): array
|
|
{
|
|
return $this->request('GET', '/pods/json');
|
|
}
|
|
|
|
public function inspectPod(string $name): array
|
|
{
|
|
return $this->request('GET', '/pods/' . rawurlencode($name) . '/json');
|
|
}
|
|
|
|
public function startPod(string $name): void
|
|
{
|
|
$this->request('POST', '/pods/' . rawurlencode($name) . '/start', [], true);
|
|
}
|
|
|
|
public function stopPod(string $name, int $timeoutSeconds = 10): void
|
|
{
|
|
$this->request('POST', '/pods/' . rawurlencode($name) . '/stop', ['t' => (string) $timeoutSeconds], true);
|
|
}
|
|
|
|
public function removePod(string $name, bool $force = false): void
|
|
{
|
|
$this->request('DELETE', '/pods/' . rawurlencode($name), ['force' => $force ? 'true' : 'false'], true);
|
|
}
|
|
|
|
// -------------------------------------------------------------------
|
|
// Images
|
|
// -------------------------------------------------------------------
|
|
|
|
public function listImages(): array
|
|
{
|
|
return $this->request('GET', '/images/json');
|
|
}
|
|
|
|
/** POST /images/pull — pulls (or updates) an image by reference, e.g. "docker.io/library/postgres:16". */
|
|
public function pullImage(string $reference): array
|
|
{
|
|
return $this->request('POST', '/images/pull', ['reference' => $reference]);
|
|
}
|
|
|
|
public function removeImage(string $id, bool $force = false): void
|
|
{
|
|
$this->request('DELETE', '/images/' . rawurlencode($id), ['force' => $force ? 'true' : 'false'], true);
|
|
}
|
|
|
|
// -------------------------------------------------------------------
|
|
// Volumes
|
|
// -------------------------------------------------------------------
|
|
|
|
public function listVolumes(): array
|
|
{
|
|
return $this->request('GET', '/volumes/json');
|
|
}
|
|
|
|
public function createVolume(string $name, string $driver = 'local'): array
|
|
{
|
|
return $this->request('POST', '/volumes/create', [], false, ['Name' => $name, 'Driver' => $driver]);
|
|
}
|
|
|
|
public function removeVolume(string $name, bool $force = false): void
|
|
{
|
|
$this->request('DELETE', '/volumes/' . rawurlencode($name), ['force' => $force ? 'true' : 'false'], true);
|
|
}
|
|
|
|
// -------------------------------------------------------------------
|
|
// Networks
|
|
// -------------------------------------------------------------------
|
|
|
|
public function listNetworks(): array
|
|
{
|
|
return $this->request('GET', '/networks/json');
|
|
}
|
|
|
|
public function createNetwork(string $name, string $driver, ?string $subnet = null, ?string $gateway = null): array
|
|
{
|
|
$body = ['name' => $name, 'driver' => $driver];
|
|
if ($subnet !== null) {
|
|
$body['subnets'] = [array_filter(['subnet' => $subnet, 'gateway' => $gateway])];
|
|
}
|
|
return $this->request('POST', '/networks/create', [], false, $body);
|
|
}
|
|
|
|
public function removeNetwork(string $name, bool $force = false): void
|
|
{
|
|
$this->request('DELETE', '/networks/' . rawurlencode($name), ['force' => $force ? 'true' : 'false'], true);
|
|
}
|
|
|
|
// -------------------------------------------------------------------
|
|
// Internals
|
|
// -------------------------------------------------------------------
|
|
|
|
/**
|
|
* Issues a request and JSON-decodes the response body.
|
|
*
|
|
* @param array<string,string> $query
|
|
* @param bool $expectEmptyBody set true for endpoints that reply 204/200 with no/irrelevant body
|
|
* @param array<mixed>|null $jsonBody request body to send as JSON, for POST/PUT endpoints that take one
|
|
* @return array<mixed>
|
|
*/
|
|
private function request(string $method, string $path, array $query = [], bool $expectEmptyBody = false, ?array $jsonBody = null): array
|
|
{
|
|
$raw = $this->requestRaw($method, $path, $query, $jsonBody);
|
|
if ($expectEmptyBody || trim($raw) === '') {
|
|
return [];
|
|
}
|
|
$decoded = json_decode($raw, true);
|
|
if (!is_array($decoded)) {
|
|
throw new PodmanApiException('Expected a JSON object/array response from ' . $path);
|
|
}
|
|
return $decoded;
|
|
}
|
|
|
|
/**
|
|
* Issues a request and returns the raw response body as a string,
|
|
* without JSON decoding — used for endpoints whose response isn't
|
|
* JSON (logs, exec start) and internally by request().
|
|
*
|
|
* @param array<string,string> $query
|
|
* @param array<mixed>|null $jsonBody
|
|
*/
|
|
private function requestRaw(string $method, string $path, array $query = [], ?array $jsonBody = null): string
|
|
{
|
|
$url = 'http://d/' . self::API_VERSION . '/libpod' . $path;
|
|
if (!empty($query)) {
|
|
$url .= '?' . http_build_query($query);
|
|
}
|
|
|
|
$ch = curl_init();
|
|
curl_setopt_array($ch, [
|
|
CURLOPT_UNIX_SOCKET_PATH => $this->socketPath,
|
|
CURLOPT_URL => $url,
|
|
CURLOPT_CUSTOMREQUEST => $method,
|
|
CURLOPT_RETURNTRANSFER => true,
|
|
CURLOPT_TIMEOUT => $this->timeoutSeconds,
|
|
CURLOPT_HTTPHEADER => ['Accept: application/json'],
|
|
]);
|
|
|
|
if ($jsonBody !== null) {
|
|
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($jsonBody));
|
|
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json', 'Accept: application/json']);
|
|
}
|
|
|
|
$body = curl_exec($ch);
|
|
$errno = curl_errno($ch);
|
|
$error = curl_error($ch);
|
|
$status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
|
|
curl_close($ch);
|
|
|
|
if ($errno !== 0) {
|
|
throw new PodmanApiException(
|
|
"Could not reach podman API socket ({$this->socketPath}): {$error}. Is rc.podman running?",
|
|
0
|
|
);
|
|
}
|
|
|
|
if ($status >= 400) {
|
|
$detail = self::extractErrorMessage($body ?: '');
|
|
throw new PodmanApiException("Podman API {$method} {$path} failed ({$status}): {$detail}", $status);
|
|
}
|
|
|
|
return $body === false ? '' : $body;
|
|
}
|
|
|
|
/** Best-effort extraction of libpod's {"cause":...,"message":...} error body shape. */
|
|
private static function extractErrorMessage(string $body): string
|
|
{
|
|
$decoded = json_decode($body, true);
|
|
if (is_array($decoded) && isset($decoded['message']) && is_string($decoded['message'])) {
|
|
return $decoded['message'];
|
|
}
|
|
return $body !== '' ? $body : '(no response body)';
|
|
}
|
|
|
|
/**
|
|
* Strips Docker/Podman's attach-stream frame headers from a
|
|
* non-TTY multiplexed stdout/stderr stream. Each frame is an 8-byte
|
|
* header — [stream type (1 byte), 0, 0, 0, big-endian uint32 length]
|
|
* — followed by that many bytes of payload. Stream type 1 = stdout,
|
|
* 2 = stderr; both are concatenated here since the UI just needs
|
|
* readable log text, not separated channels.
|
|
*/
|
|
private static function demuxStream(string $raw): string
|
|
{
|
|
if ($raw === '') {
|
|
return '';
|
|
}
|
|
// If the stream doesn't start with a recognizable frame header,
|
|
// assume it's already plain text (e.g. a TTY-attached container's
|
|
// logs, which libpod does not frame) and return it as-is.
|
|
$firstByte = ord($raw[0]);
|
|
if ($firstByte > 2) {
|
|
return $raw;
|
|
}
|
|
|
|
$out = '';
|
|
$offset = 0;
|
|
$len = strlen($raw);
|
|
while ($offset + 8 <= $len) {
|
|
$header = substr($raw, $offset, 8);
|
|
$unpacked = unpack('Ctype/C3pad/Nsize', $header);
|
|
if ($unpacked === false) {
|
|
break;
|
|
}
|
|
$frameLen = $unpacked['size'];
|
|
$offset += 8;
|
|
if ($offset + $frameLen > $len) {
|
|
// Truncated final frame — take what's left and stop.
|
|
$out .= substr($raw, $offset);
|
|
break;
|
|
}
|
|
$out .= substr($raw, $offset, $frameLen);
|
|
$offset += $frameLen;
|
|
}
|
|
return $out;
|
|
}
|
|
}
|