toga-ai 1.0.18 → 1.0.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,49 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Error Response Envelope
|
|
3
|
-
framework: "2.0"
|
|
4
|
-
repo: api2
|
|
5
|
-
project: API
|
|
6
|
-
client: shared
|
|
7
|
-
type: feature
|
|
8
|
-
status: active
|
|
9
|
-
updated: 2026-06-09
|
|
10
|
-
owners: []
|
|
11
|
-
files:
|
|
12
|
-
- api2/Controller/Index.php
|
|
13
|
-
related:
|
|
14
|
-
- 2.0/apps/api2/architecture.md
|
|
15
|
-
- 2.0/apps/api2/features/health-endpoint.md
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
## Summary
|
|
19
|
-
Every api2 action method returns the same three-key envelope. Clients depend on
|
|
20
|
-
this contract — deviating from it breaks consumers silently.
|
|
21
|
-
|
|
22
|
-
## Envelope structure
|
|
23
|
-
```php
|
|
24
|
-
return [
|
|
25
|
-
'success' => true, // bool
|
|
26
|
-
'data' => $result, // mixed — null on error
|
|
27
|
-
'errors' => [], // string[] — empty on success
|
|
28
|
-
];
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
## Error response
|
|
32
|
-
```php
|
|
33
|
-
return [
|
|
34
|
-
'success' => false,
|
|
35
|
-
'data' => null,
|
|
36
|
-
'errors' => ['Order not found'],
|
|
37
|
-
];
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## HTTP status codes
|
|
41
|
-
The framework maps `success: false` responses to HTTP 4xx/5xx via the controller
|
|
42
|
-
base class. Do not manually set status codes — return the envelope and let the
|
|
43
|
-
framework decide.
|
|
44
|
-
|
|
45
|
-
## Gotchas / known issues
|
|
46
|
-
- Never return a raw string or a bare array — the JS client checks `response.success`
|
|
47
|
-
and crashes if the key is missing.
|
|
48
|
-
- `errors` must always be an array, even for a single error. Never pass a string.
|
|
49
|
-
- `data` must be present even on error — pass `null`, not omit the key.
|
|
@@ -1,47 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Health Check Endpoint
|
|
3
|
-
framework: "2.0"
|
|
4
|
-
repo: api2
|
|
5
|
-
project: API
|
|
6
|
-
client: shared
|
|
7
|
-
type: feature
|
|
8
|
-
status: active
|
|
9
|
-
updated: 2026-06-09
|
|
10
|
-
owners: [jcardinal]
|
|
11
|
-
files:
|
|
12
|
-
- api2/Controller/Index.php
|
|
13
|
-
related:
|
|
14
|
-
- 2.0/apps/api2/architecture.md
|
|
15
|
-
---
|
|
16
|
-
|
|
17
|
-
## Summary
|
|
18
|
-
|
|
19
|
-
`GET /health` returns HTTP 200 with an empty JSON object (`{}`). It exists solely for
|
|
20
|
-
Elastic Beanstalk and load-balancer health probes — not for application-level health
|
|
21
|
-
checks.
|
|
22
|
-
|
|
23
|
-
## How it works
|
|
24
|
-
|
|
25
|
-
The route is handled in `Controller/Index.php` `api()` before any authentication, DB
|
|
26
|
-
registration, or Sentry initialization runs. This keeps it as fast and dependency-free
|
|
27
|
-
as possible so EB/ALB probes never time out due to a slow DB or misconfigured secret.
|
|
28
|
-
|
|
29
|
-
```
|
|
30
|
-
GET /health
|
|
31
|
-
→ Controller/Index.php::api()
|
|
32
|
-
→ early-exit: echo '{}', HTTP 200
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Gotchas / known issues
|
|
36
|
-
|
|
37
|
-
- **Never add auth or DB calls to this route.** The probe fires every few seconds from
|
|
38
|
-
every AZ. Adding overhead here will cause false-positive unhealthy marks and
|
|
39
|
-
unnecessary instance replacements.
|
|
40
|
-
- **Do not change the response body.** Some ALB rules pattern-match on `{}`. A non-empty
|
|
41
|
-
body or a different content type may cause the probe to fail even on HTTP 200.
|
|
42
|
-
- If the endpoint starts returning non-200, EB will terminate and replace the instance —
|
|
43
|
-
you will lose in-flight requests with no warning in application logs.
|
|
44
|
-
|
|
45
|
-
## Related docs
|
|
46
|
-
|
|
47
|
-
- [api2 Architecture](../architecture.md)
|