openstatus.dev
Openstatus
www.openstatus.dev
1# Status Page Proto Service Implementation Plan
2
3## Overview
4
5Create a new proto service for Status Pages in `packages/proto/api/openstatus/status_page/v1/` following existing patterns from `monitor` and `status_report` services.
6
7## File Structure
8
9```
10packages/proto/api/openstatus/status_page/v1/
11├── service.proto # RPC service definitions
12├── status_page.proto # StatusPage message and enums
13├── page_component.proto # PageComponent message and enums
14└── page_subscriber.proto # PageSubscriber message
15```
16
17## Proto Definitions
18
19### 1. `status_page.proto` - Core Types
20
21**Enums:**
22- `PageAccessType`: PUBLIC, PASSWORD_PROTECTED, AUTHENTICATED
23- `PageTheme`: SYSTEM, LIGHT, DARK
24- `OverallStatus`: OPERATIONAL, DEGRADED, PARTIAL_OUTAGE, MAJOR_OUTAGE, MAINTENANCE, UNKNOWN
25
26**Messages:**
27- `StatusPage` - Full page details (id, title, description, slug, custom_domain, published, access_type, theme, homepage_url, contact_url, icon, timestamps)
28- `StatusPageSummary` - List response (id, title, slug, published, timestamps)
29
30### 2. `page_component.proto` - Component Types
31
32**Enums:**
33- `PageComponentType`: MONITOR, STATIC
34
35**Messages:**
36- `PageComponent` - Component details (id, page_id, name, description, type, monitor_id, order, group_id, group_order, timestamps)
37- `PageComponentGroup` - Group details (id, page_id, name, timestamps)
38
39### 3. `page_subscriber.proto` - Subscriber Types
40
41**Messages:**
42- `PageSubscriber` - Subscriber details (id, page_id, email, accepted_at, unsubscribed_at, timestamps)
43
44### 4. `service.proto` - RPC Service
45
46```protobuf
47service StatusPageService {
48 // Page CRUD
49 rpc CreateStatusPage(CreateStatusPageRequest) returns (CreateStatusPageResponse);
50 rpc GetStatusPage(GetStatusPageRequest) returns (GetStatusPageResponse);
51 rpc ListStatusPages(ListStatusPagesRequest) returns (ListStatusPagesResponse);
52 rpc UpdateStatusPage(UpdateStatusPageRequest) returns (UpdateStatusPageResponse);
53 rpc DeleteStatusPage(DeleteStatusPageRequest) returns (DeleteStatusPageResponse);
54
55 // Components
56 rpc AddMonitorComponent(AddMonitorComponentRequest) returns (AddMonitorComponentResponse);
57 rpc AddExternalComponent(AddExternalComponentRequest) returns (AddExternalComponentResponse);
58 rpc RemoveComponent(RemoveComponentRequest) returns (RemoveComponentResponse);
59 rpc UpdateComponent(UpdateComponentRequest) returns (UpdateComponentResponse);
60
61 // Component Groups
62 rpc CreateComponentGroup(CreateComponentGroupRequest) returns (CreateComponentGroupResponse);
63 rpc DeleteComponentGroup(DeleteComponentGroupRequest) returns (DeleteComponentGroupResponse);
64 rpc UpdateComponentGroup(UpdateComponentGroupRequest) returns (UpdateComponentGroupResponse);
65
66 // Subscribers
67 rpc SubscribeToPage(SubscribeToPageRequest) returns (SubscribeToPageResponse);
68 rpc UnsubscribeFromPage(UnsubscribeFromPageRequest) returns (UnsubscribeFromPageResponse);
69 rpc ListSubscribers(ListSubscribersRequest) returns (ListSubscribersResponse);
70
71 // Full Content & Status
72 rpc GetStatusPageContent(GetStatusPageContentRequest) returns (GetStatusPageContentResponse);
73 rpc GetOverallStatus(GetOverallStatusRequest) returns (GetOverallStatusResponse);
74}
75```
76
77## RPC Methods Breakdown
78
79### Page CRUD (5 methods)
80| Method | Request Fields | Response |
81|--------|---------------|----------|
82| `CreateStatusPage` | title, description, slug, homepage_url?, contact_url?| StatusPage |
83| `GetStatusPage` | id | StatusPage |
84| `ListStatusPages` | limit?, offset? | StatusPageSummary[], total_size |
85| `UpdateStatusPage` | id, title?, description?, slug?, homepage_url?, contact_url? | StatusPage |
86| `DeleteStatusPage` | id | success |
87
88### Component Management (4 methods)
89| Method | Request Fields | Response |
90|--------|---------------|----------|
91| `AddMonitorComponent` | page_id, monitor_id, name?, description?, order?, group_id? | PageComponent |
92| `AddExternalComponent` | page_id, name, description?, order?, group_id? | PageComponent |
93| `RemoveComponent` | id | success |
94| `UpdateComponent` | id, name?, description?, order?, group_id?, group_order? | PageComponent |
95
96### Component Groups (3 methods)
97| Method | Request Fields | Response |
98|--------|---------------|----------|
99| `CreateComponentGroup` | page_id, name | PageComponentGroup |
100| `DeleteComponentGroup` | id | success |
101| `UpdateComponentGroup` | id, name? | PageComponentGroup |
102
103### Subscriber Management (3 methods)
104| Method | Request Fields | Response |
105|--------|---------------|----------|
106| `SubscribeToPage` | page_id, email | PageSubscriber |
107| `UnsubscribeFromPage` | page_id, email or token | success |
108| `ListSubscribers` | page_id, limit?, offset?, include_unsubscribed? | PageSubscriber[], total_size |
109
110### Full Content & Status (2 methods)
111| Method | Request Fields | Response |
112|--------|---------------|----------|
113| `GetStatusPageContent` | id or slug | StatusPage, components[], groups[], status_reports[], maintenances[] |
114| `GetOverallStatus` | id or slug | overall_status, component_statuses[] |
115
116## Validation Rules (using buf.validate)
117
118- `title`: min_len=1, max_len=256
119- `description`: max_len=1024
120- `slug`: min_len=1, max_len=256, pattern for valid slug
121- `email`: email format validation
122- `limit`: gte=1, lte=100
123- `offset`: gte=0
124- Enums: defined_only=true, not_in=[0] where appropriate
125
126## Implementation Order
127
1281. Create `status_page.proto` with enums and base messages
1292. Create `page_component.proto` with component types
1303. Create `page_subscriber.proto` with subscriber message
1314. Create `service.proto` with all RPC definitions
1325. Update buf.yaml if needed to include new package
133
134## Files to Create
135
136| File | Description |
137|------|-------------|
138| `packages/proto/api/openstatus/status_page/v1/status_page.proto` | Core enums and StatusPage messages |
139| `packages/proto/api/openstatus/status_page/v1/page_component.proto` | PageComponent and PageComponentGroup messages |
140| `packages/proto/api/openstatus/status_page/v1/page_subscriber.proto` | PageSubscriber message |
141| `packages/proto/api/openstatus/status_page/v1/service.proto` | StatusPageService RPC definitions |
142
143## Verification
144
1451. Run `pnpm buf lint` to verify proto files are valid
1462. Run `pnpm buf generate` to generate Go/TS code
1473. Check generated code compiles without errors