Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00% covered (success)
100.00%
17 / 17
100.00% covered (success)
100.00%
7 / 7
CRAP
100.00% covered (success)
100.00%
1 / 1
ZeusForwardResult
100.00% covered (success)
100.00%
17 / 17
100.00% covered (success)
100.00%
7 / 7
11
100.00% covered (success)
100.00%
1 / 1
 __construct
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 skipped
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 sent
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 failed
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 successful
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
2
 isRead
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 toTitanResponse
100.00% covered (success)
100.00%
11 / 11
100.00% covered (success)
100.00%
1 / 1
4
1<?php
2
3namespace App\Services;
4
5use Illuminate\Http\Client\Response;
6
7/**
8 * Outcome of one Titan → Zeus forward attempt.
9 *
10 * Three shapes, and the controller only ever has to care about two questions:
11 * did we forward at all, and may we hand Zeus's answer back to the third party.
12 *
13 * - `skipped`   — not a bridged region / not a bridged caller / bridge off.
14 *                 Titan handles the operation exactly as it always has.
15 * - `sent`      — Zeus answered. `successful()` says whether it accepted it.
16 * - `failed`    — Zeus was unreachable or errored out. Titan falls back to its
17 *                 own handling; the attempt is in `tbl_zeus_bridge_log`.
18 *
19 * `kind` separates the two halves of the bridge. A **write** is mirrored by
20 * default (Titan saves too and answers with its own response), so Zeus's answer
21 * is only returned in `forward` mode. A **read** has nothing to mirror — there is
22 * no second copy to save — so a successful read is always answered with Zeus's
23 * response, whatever `zeus.mode` says.
24 */
25class ZeusForwardResult
26{
27    public const KIND_WRITE = 'write';
28
29    public const KIND_READ = 'read';
30
31    /** Response headers passed straight through to the third party. */
32    private const PASSTHROUGH_HEADERS = [
33        'Content-Type',
34        'Content-Disposition',
35        'Content-Length',
36        'Cache-Control',
37    ];
38
39    private function __construct(
40        public readonly bool $forwarded,
41        public readonly ?string $region,
42        public readonly string $kind = self::KIND_WRITE,
43        public readonly ?Response $response = null,
44        public readonly ?\Throwable $error = null,
45    ) {}
46
47    public static function skipped(?string $region, string $kind = self::KIND_WRITE): self
48    {
49        return new self(false, $region, $kind);
50    }
51
52    public static function sent(?string $region, Response $response, string $kind = self::KIND_WRITE): self
53    {
54        return new self(true, $region, $kind, $response);
55    }
56
57    public static function failed(?string $region, \Throwable $error, string $kind = self::KIND_WRITE): self
58    {
59        return new self(true, $region, $kind, null, $error);
60    }
61
62    /** Zeus accepted the operation. */
63    public function successful(): bool
64    {
65        return $this->response !== null && $this->response->successful();
66    }
67
68    public function isRead(): bool
69    {
70        return $this->kind === self::KIND_READ;
71    }
72
73    /**
74     * Zeus's answer, ready to be returned to the third party as Titan's own.
75     * Status, body and the passthrough headers are copied verbatim so the caller
76     * cannot tell the difference — including `downloadFile`, where the body is
77     * raw bytes and `Content-Disposition` carries the filename.
78     */
79    public function toTitanResponse(): \Illuminate\Http\Response
80    {
81        $headers = [];
82
83        foreach (self::PASSTHROUGH_HEADERS as $header) {
84            $value = $this->response?->header($header);
85
86            if ($value !== null && $value !== '') {
87                $headers[$header] = $value;
88            }
89        }
90
91        $headers['Content-Type'] ??= 'application/json';
92
93        return response(
94            $this->response?->body() ?? '',
95            $this->response?->status() ?? 502,
96            $headers,
97        );
98    }
99}