Skip to content

Commit 62a07ba

Browse files
ma-hillma-hill
committed
HYPERFLEET-978 - feat: Add PUT command for internal status endpoints (2/2)
1 parent 98cfd7e commit 62a07ba

6 files changed

Lines changed: 26 additions & 253 deletions

File tree

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ The `aliases.tsp` symlink determines which provider types are active. The `build
4646

4747
Status endpoints are split:
4848
- `services/statuses.tsp` - GET operations (external clients)
49-
- `services/statuses-internal.tsp` - POST operations (internal adapters only)
49+
- `services/statuses-internal.tsp` - PUT operations (internal adapters only)
5050

5151
The split allows generating different API contracts per audience. Only `statuses.tsp` is imported by default.
5252

‎README.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ Contains service definitions that generate the OpenAPI specifications:
110110

111111
- **`services/clusters.tsp`** - Cluster resource endpoints
112112
- **`services/statuses.tsp`** - Status resource endpoints (GET only - public API)
113-
- **`services/statuses-internal.tsp`** - Status write endpoints (POST/PUT - internal API, see below)
113+
- **`services/statuses-internal.tsp`** - Status write endpoints (PUT - internal API, see below)
114114
- **`services/nodepools.tsp`** - NodePool resource endpoints
115115

116116
#### Public vs Internal API Split
@@ -120,7 +120,6 @@ The status endpoints are split into two files to support different API consumers
120120
| File | Operations | Audience | Included in Build |
121121
|------|------------|----------|-------------------|
122122
| `statuses.tsp` | GET (read) | External clients | ✅ Yes (default) |
123-
| `statuses-internal.tsp` | POST (write) | Internal adapters | ❌ No (opt-in) |
124123
| `statuses-internal.tsp` | PUT (write) | Internal adapters | ❌ No (opt-in) |
125124

126125
**Why the split?**

‎models/statuses/example_adapter_status.tsp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ const exampleAdapterStatus: AdapterStatus = (#{
5454
last_report_time: "2021-01-01T10:02:00Z",
5555
});
5656

57-
// Example AdapterStatusCreateRequest (for POST /clusters/{id}/statuses)
57+
// Example AdapterStatusCreateRequest (for PUT /clusters/{id}/statuses)
5858
const exampleAdapterStatusCreateRequest: AdapterStatusCreateRequest = (#{
5959
adapter: "validator",
6060
observed_generation: 1,

‎schemas/core/openapi.yaml‎

Lines changed: 5 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -507,55 +507,10 @@ paths:
507507
security:
508508
- BearerAuth: []
509509
/api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses:
510-
post:
511-
operationId: postNodePoolStatuses
512-
summary: Create or update adapter status
513-
description: |-
514-
Adapter creates or updates its status report for this nodepool.
515-
If adapter already has a status, it will be updated (upsert by adapter name).
516-
517-
Response includes the full adapter status with all conditions.
518-
Adapter should call this endpoint every time it evaluates the nodepool.
519-
parameters:
520-
- name: cluster_id
521-
in: path
522-
required: true
523-
description: Cluster ID
524-
schema:
525-
type: string
526-
- name: nodepool_id
527-
in: path
528-
required: true
529-
description: Nodepool ID
530-
schema:
531-
type: string
532-
responses:
533-
'201':
534-
description: The request has succeeded and a new resource has been created as a result.
535-
content:
536-
application/json:
537-
schema:
538-
$ref: '#/components/schemas/AdapterStatus'
539-
'400':
540-
description: The server could not understand the request due to invalid syntax.
541-
'404':
542-
description: The server cannot find the requested resource.
543-
'409':
544-
description: The request conflicts with the current state of the server.
545-
tags:
546-
- NodePool statuses
547-
requestBody:
548-
required: true
549-
content:
550-
application/json:
551-
schema:
552-
$ref: '#/components/schemas/AdapterStatusCreateRequest'
553-
security:
554-
- BearerAuth: []
555510
put:
556511
operationId: putNodePoolStatuses
557-
summary: Adapter creates or updates resource nodepool status
558-
description: Idempotent upsert of an adapter status for this nodepool. Use instead of POST when the adapter name is known upfront.
512+
summary: Adapter creates or updates nodepool status
513+
description: Adapters call this endpoint to report the status for a nodepool after each evaluation. The adapter's status entry is created if it doesn't exist, or updated if it does (upserted by adapter name). This allows HyperFleet to aggregate multiple adapter perspectives into a unified nodepool status.
559514
parameters:
560515
- name: cluster_id
561516
in: path
@@ -566,7 +521,7 @@ paths:
566521
- name: nodepool_id
567522
in: path
568523
required: true
569-
description: Nodepool ID
524+
description: NodePool ID
570525
schema:
571526
type: string
572527
responses:
@@ -631,49 +586,10 @@ paths:
631586
tags:
632587
- NodePool statuses
633588
/api/hyperfleet/v1/clusters/{cluster_id}/statuses:
634-
post:
635-
operationId: postClusterStatuses
636-
summary: Create or update adapter status
637-
description: |-
638-
Adapter creates or updates its status report for this cluster.
639-
If adapter already has a status, it will be updated (upsert by adapter name).
640-
641-
Response includes the full adapter status with all conditions.
642-
Adapter should call this endpoint every time it evaluates the cluster.
643-
parameters:
644-
- name: cluster_id
645-
in: path
646-
required: true
647-
description: Cluster ID
648-
schema:
649-
type: string
650-
responses:
651-
'201':
652-
description: The request has succeeded and a new resource has been created as a result.
653-
content:
654-
application/json:
655-
schema:
656-
$ref: '#/components/schemas/AdapterStatus'
657-
'400':
658-
description: The server could not understand the request due to invalid syntax.
659-
'404':
660-
description: The server cannot find the requested resource.
661-
'409':
662-
description: The request conflicts with the current state of the server.
663-
tags:
664-
- Cluster statuses
665-
requestBody:
666-
required: true
667-
content:
668-
application/json:
669-
schema:
670-
$ref: '#/components/schemas/AdapterStatusCreateRequest'
671-
security:
672-
- BearerAuth: []
673589
put:
674590
operationId: putClusterStatuses
675-
summary: Adapter creates or updates resource cluster status
676-
description: Idempotent upsert of an adapter status for this cluster. Use instead of POST when the adapter name is known upfront.
591+
summary: Adapter creates or updates cluster status
592+
description: Adapters call this endpoint to report the status for a cluster after each evaluation. The adapter's status entry is created if it doesn't exist, or updated if it does (upserted by adapter name). This allows HyperFleet to aggregate multiple adapter perspectives into a unified cluster status.
677593
parameters:
678594
- name: cluster_id
679595
in: path

‎schemas/core/swagger.yaml‎

Lines changed: 13 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -655,56 +655,6 @@ paths:
655655
description: Returns adapter status reports for this nodepool
656656
operationId: getNodePoolsStatuses
657657
summary: List all adapter statuses for nodepools
658-
post:
659-
consumes:
660-
- application/json
661-
produces:
662-
- application/json
663-
parameters:
664-
- description: Cluster ID
665-
in: path
666-
name: cluster_id
667-
required: true
668-
type: string
669-
- description: Nodepool ID
670-
in: path
671-
name: nodepool_id
672-
required: true
673-
type: string
674-
- in: body
675-
name: body
676-
required: true
677-
schema:
678-
$ref: '#/definitions/AdapterStatusCreateRequest'
679-
responses:
680-
'201':
681-
description: >-
682-
The request has succeeded and a new resource has been created as a
683-
result.
684-
schema:
685-
$ref: '#/definitions/AdapterStatus'
686-
'400':
687-
description: The server could not understand the request due to invalid syntax.
688-
'404':
689-
description: The server cannot find the requested resource.
690-
'409':
691-
description: The request conflicts with the current state of the server.
692-
security:
693-
- BearerAuth: []
694-
tags:
695-
- NodePool statuses
696-
description: >-
697-
Adapter creates or updates its status report for this nodepool.
698-
699-
If adapter already has a status, it will be updated (upsert by adapter
700-
name).
701-
702-
703-
Response includes the full adapter status with all conditions.
704-
705-
Adapter should call this endpoint every time it evaluates the nodepool.
706-
operationId: postNodePoolStatuses
707-
summary: Create or update adapter status
708658
put:
709659
consumes:
710660
- application/json
@@ -716,7 +666,7 @@ paths:
716666
name: cluster_id
717667
required: true
718668
type: string
719-
- description: Nodepool ID
669+
- description: NodePool ID
720670
in: path
721671
name: nodepool_id
722672
required: true
@@ -744,10 +694,13 @@ paths:
744694
tags:
745695
- NodePool statuses
746696
description: >-
747-
Idempotent upsert of an adapter status for this nodepool. Use instead of
748-
POST when the adapter name is known upfront.
697+
Adapters call this endpoint to report the status for a nodepool after
698+
each evaluation. The adapter's status entry is created if it doesn't
699+
exist, or updated if it does (upserted by adapter name). This allows
700+
HyperFleet to aggregate multiple adapter perspectives into a unified
701+
nodepool status.
749702
operationId: putNodePoolStatuses
750-
summary: Adapter creates or updates resource nodepool status
703+
summary: Adapter creates or updates nodepool status
751704
'/api/hyperfleet/v1/clusters/{cluster_id}/statuses':
752705
get:
753706
produces:
@@ -807,51 +760,6 @@ paths:
807760
description: Returns adapter status reports for this cluster
808761
operationId: getClusterStatuses
809762
summary: List all adapter statuses for cluster
810-
post:
811-
consumes:
812-
- application/json
813-
produces:
814-
- application/json
815-
parameters:
816-
- description: Cluster ID
817-
in: path
818-
name: cluster_id
819-
required: true
820-
type: string
821-
- in: body
822-
name: body
823-
required: true
824-
schema:
825-
$ref: '#/definitions/AdapterStatusCreateRequest'
826-
responses:
827-
'201':
828-
description: >-
829-
The request has succeeded and a new resource has been created as a
830-
result.
831-
schema:
832-
$ref: '#/definitions/AdapterStatus'
833-
'400':
834-
description: The server could not understand the request due to invalid syntax.
835-
'404':
836-
description: The server cannot find the requested resource.
837-
'409':
838-
description: The request conflicts with the current state of the server.
839-
security:
840-
- BearerAuth: []
841-
tags:
842-
- Cluster statuses
843-
description: >-
844-
Adapter creates or updates its status report for this cluster.
845-
846-
If adapter already has a status, it will be updated (upsert by adapter
847-
name).
848-
849-
850-
Response includes the full adapter status with all conditions.
851-
852-
Adapter should call this endpoint every time it evaluates the cluster.
853-
operationId: postClusterStatuses
854-
summary: Create or update adapter status
855763
put:
856764
consumes:
857765
- application/json
@@ -886,10 +794,13 @@ paths:
886794
tags:
887795
- Cluster statuses
888796
description: >-
889-
Idempotent upsert of an adapter status for this cluster. Use instead of
890-
POST when the adapter name is known upfront.
797+
Adapters call this endpoint to report the status for a cluster after
798+
each evaluation. The adapter's status entry is created if it doesn't
799+
exist, or updated if it does (upserted by adapter name). This allows
800+
HyperFleet to aggregate multiple adapter perspectives into a unified
801+
cluster status.
891802
operationId: putClusterStatuses
892-
summary: Adapter creates or updates resource cluster status
803+
summary: Adapter creates or updates cluster status
893804
/api/hyperfleet/v1/nodepools:
894805
get:
895806
produces:

‎services/statuses-internal.tsp‎

Lines changed: 5 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -15,35 +15,11 @@ namespace HyperFleet;
1515
@useAuth(HyperFleet.BearerAuth)
1616
@tag("Cluster statuses")
1717
interface ClusterStatusesInternal {
18-
/**
19-
* Adapter creates or updates its status report for this cluster.
20-
* If adapter already has a status, it will be updated (upsert by adapter name).
21-
*
22-
* Response includes the full adapter status with all conditions.
23-
* Adapter should call this endpoint every time it evaluates the cluster.
24-
*/
25-
@route("")
26-
@post
27-
@summary("Create or update adapter status")
28-
@operationId("postClusterStatuses")
29-
postClusterStatuses(
30-
/**
31-
* Cluster ID
32-
*/
33-
@path cluster_id: string,
34-
35-
@body body: AdapterStatusCreateRequest,
36-
):
37-
| (CreatedResponse & AdapterStatus)
38-
| BadRequestResponse
39-
| NotFoundResponse
40-
| ConflictResponse;
41-
4218
@route("")
4319
@put
44-
@summary("Adapter creates or updates resource cluster status")
20+
@summary("Adapter creates or updates cluster status")
4521
@operationId("putClusterStatuses")
46-
@doc("Idempotent upsert of an adapter status for this cluster. Use instead of POST when the adapter name is known upfront.")
22+
@doc("Adapters call this endpoint to report the status for a cluster after each evaluation. The adapter's status entry is created if it doesn't exist, or updated if it does (upserted by adapter name). This allows HyperFleet to aggregate multiple adapter perspectives into a unified cluster status.")
4723
putClusterStatuses(
4824
/**
4925
* Cluster ID
@@ -62,48 +38,19 @@ interface ClusterStatusesInternal {
6238
@route("/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses")
6339
@useAuth(HyperFleet.BearerAuth)
6440
interface NodePoolStatusesInternal {
65-
/**
66-
* Adapter creates or updates its status report for this nodepool.
67-
* If adapter already has a status, it will be updated (upsert by adapter name).
68-
*
69-
* Response includes the full adapter status with all conditions.
70-
* Adapter should call this endpoint every time it evaluates the nodepool.
71-
*/
72-
@route("")
73-
@post
74-
@summary("Create or update adapter status")
75-
@operationId("postNodePoolStatuses")
76-
postNodePoolStatuses(
77-
/**
78-
* Cluster ID
79-
*/
80-
@path cluster_id: string,
81-
82-
/**
83-
* Nodepool ID
84-
*/
85-
@path nodepool_id: string,
86-
87-
@body body: AdapterStatusCreateRequest,
88-
):
89-
| (CreatedResponse & AdapterStatus)
90-
| BadRequestResponse
91-
| NotFoundResponse
92-
| ConflictResponse;
93-
9441
@route("")
9542
@put
96-
@summary("Adapter creates or updates resource nodepool status")
43+
@summary("Adapter creates or updates nodepool status")
9744
@operationId("putNodePoolStatuses")
98-
@doc("Idempotent upsert of an adapter status for this nodepool. Use instead of POST when the adapter name is known upfront.")
45+
@doc("Adapters call this endpoint to report the status for a nodepool after each evaluation. The adapter's status entry is created if it doesn't exist, or updated if it does (upserted by adapter name). This allows HyperFleet to aggregate multiple adapter perspectives into a unified nodepool status.")
9946
putNodePoolStatuses(
10047
/**
10148
* Cluster ID
10249
*/
10350
@path cluster_id: string,
10451

10552
/**
106-
* Nodepool ID
53+
* NodePool ID
10754
*/
10855
@path nodepool_id: string,
10956

0 commit comments

Comments
 (0)