feat(api): split public and internal routes

Author: pixel365

README.md

@@ -32,6 +32,7 @@ What exists today:
 - gRPC health checks via `grpc.health.v1.Health/Check`
 - PostgreSQL-backed raw check execution storage
 - persisted current check state
+- persisted check state event history
 - migration CLI via `cmd/pulse-migrate`
 - early REST API via `cmd/pulse-api`
 
@@ -79,23 +80,33 @@ CONFIG_DIR=./examples go run ./cmd/pulse
 Run API with:
 
 ```bash
-API_LISTEN_ADDR=:8080 CONFIG_DIR=./examples go run ./cmd/pulse-api
+API_LISTEN_ADDR=:8080 INTERNAL_API_ENABLED=true CONFIG_DIR=./examples go run ./cmd/pulse-api
 ```
 
-Implemented API endpoints:
+The API process has separate internal and public route groups.
+Both are disabled by default and must be enabled explicitly:
 
-- `GET /v1/services`
-- `GET /v1/services/{serviceId}/checks/state`
-- `GET /v1/services/{serviceId}/checks/{checkId}/executions`
-- `GET /v1/services/{serviceId}/checks/{checkId}/timeline`
-- `GET /v1/services/{serviceId}/checks/{checkId}/buckets`
+- `INTERNAL_API_ENABLED=true` enables monitoring/admin-oriented endpoints
+- `PUBLIC_API_ENABLED=true` enables public status endpoints
+
+Implemented internal API endpoints:
+
+- `GET /internal/v1/services`
+- `GET /internal/v1/services/{serviceId}/checks/state`
+- `GET /internal/v1/services/{serviceId}/checks/{checkId}/executions`
+- `GET /internal/v1/services/{serviceId}/checks/{checkId}/timeline`
+- `GET /internal/v1/services/{serviceId}/checks/{checkId}/buckets`
+
+Placeholder public API endpoints:
+
+- `GET /public/v1/status`
 
 ## Notes
 
 A few implementation details are intentionally narrow at this stage:
 
 - gRPC support currently targets only the standard health check API: `grpc.health.v1.Health/Check`
-- raw execution history and current check state are stored in PostgreSQL
+- raw execution history, current check state, and check state event history are stored in PostgreSQL
 - API configuration is read from the latest valid hot-reloaded config snapshot
 - internal architecture is still evolving
 - timeline and bucket endpoints respect per-check `allowed_buckets`

examples/checks/api-checks.yaml

@@ -10,7 +10,7 @@ checks:
     retries: 3
     failure_threshold: 3
     allowed_buckets: [ minute, hour ]
-    tags: [ public, critical ]
+    status_impact: critical
     spec:
       url: http://localhost:8080
       method: GET
@@ -38,7 +38,7 @@ checks:
     retries: 3
     failure_threshold: 3
     allowed_buckets: [ minute, hour ]
-    tags: [ public, critical ]
+    status_impact: critical
     spec:
       host: localhost
       port: 8080
@@ -57,7 +57,7 @@ checks:
     retries: 3
     failure_threshold: 3
     allowed_buckets: [ minute, hour ]
-    tags: [ internal, critical ]
+    status_impact: major
     spec:
       host: localhost
       port: 8080
@@ -80,7 +80,7 @@ checks:
     retries: 3
     failure_threshold: 3
     allowed_buckets: [ minute, hour ]
-    tags: [ public, critical ]
+    status_impact: critical
     spec:
       server: 8.8.8.8
       name: api.example.com
@@ -100,7 +100,7 @@ checks:
     retries: 2
     failure_threshold: 2
     allowed_buckets: [ hour, day ]
-    tags: [ public, security ]
+    status_impact: critical
     spec:
       host: api.example.com
       port: 443

internal/api/router.go

@@ -1,13 +1,46 @@
 package api
 
-import "github.com/go-chi/chi/v5"
+import (
+	"net/http"
+	"os"
+	"strconv"
+
+	"github.com/go-chi/chi/v5"
+)
 
 func Routes(r chi.Router, h *Handler) {
-	r.Route("/v1", func(r chi.Router) {
-		r.Get("/services", h.Services)
-		r.Get("/services/{serviceId}/checks/state", h.ServiceCheckStates)
-		r.Get("/services/{serviceId}/checks/{checkId}/executions", h.CheckExecutions)
-		r.Get("/services/{serviceId}/checks/{checkId}/timeline", h.CheckTimeline)
-		r.Get("/services/{serviceId}/checks/{checkId}/buckets", h.CheckBuckets)
+	public(r, h)
+	internal(r, h)
+}
+
+func public(r chi.Router, h *Handler) {
+	enabled, _ := strconv.ParseBool(os.Getenv("PUBLIC_API_ENABLED"))
+	if !enabled {
+		return
+	}
+
+	r.Route("/public", func(r chi.Router) {
+		r.Route("/v1", func(r chi.Router) {
+			r.Get("/status", func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusNotImplemented)
+			})
+		})
+	})
+}
+
+func internal(r chi.Router, h *Handler) {
+	enabled, _ := strconv.ParseBool(os.Getenv("INTERNAL_API_ENABLED"))
+	if !enabled {
+		return
+	}
+
+	r.Route("/internal", func(r chi.Router) {
+		r.Route("/v1", func(r chi.Router) {
+			r.Get("/services", h.Services)
+			r.Get("/services/{serviceId}/checks/state", h.ServiceCheckStates)
+			r.Get("/services/{serviceId}/checks/{checkId}/executions", h.CheckExecutions)
+			r.Get("/services/{serviceId}/checks/{checkId}/timeline", h.CheckTimeline)
+			r.Get("/services/{serviceId}/checks/{checkId}/buckets", h.CheckBuckets)
+		})
 	})
 }

internal/app/manager.go

@@ -383,7 +383,6 @@ func sameCheckFields(a, b config.CheckFields) bool {
 		a.Name == b.Name &&
 		a.Service == b.Service &&
 		a.Type == b.Type &&
-		slices.Equal(a.Tags, b.Tags) &&
 		a.Timeout == b.Timeout &&
 		a.Jitter == b.Jitter &&
 		a.Retries == b.Retries &&

internal/config/model.go

@@ -12,6 +12,7 @@ type GRPCHealthStatus string
 type RecordType string
 type GRPCHealthService string
 type GRPCHealthMethod string
+type StatusImpact string
 
 const (
 	HTTP CheckType = "http"
@@ -35,6 +36,11 @@ const (
 
 	HealthService GRPCHealthService = "grpc.health.v1.Health"
 	HealthMethod  GRPCHealthMethod  = "Check"
+
+	StatusImpactNone     StatusImpact = "none"
+	StatusImpactMinor    StatusImpact = "minor"
+	StatusImpactMajor    StatusImpact = "major"
+	StatusImpactCritical StatusImpact = "critical"
 )
 
 type Comparer[T any] interface {
@@ -67,17 +73,17 @@ type Service struct {
 
 //nolint:lll
 type CheckFields struct {
-	ID               string        `yaml:"id"                json:"id"                validate:"required,min=1"`
+	StatusImpact     StatusImpact  `yaml:"status_impact"     json:"status_impact"     validate:"required,oneof=none minor major critical"`
 	Name             string        `yaml:"name"              json:"name"              validate:"required,min=1"`
 	Service          string        `yaml:"service"           json:"service"           validate:"required,min=1"`
 	Type             CheckType     `yaml:"type"              json:"type"              validate:"required,oneof=http tcp grpc tls dns"`
-	Tags             []string      `yaml:"tags"              json:"tags"              validate:"omitempty,min=1,dive,min=1"`
+	ID               string        `yaml:"id"                json:"id"                validate:"required,min=1"`
 	AllowedBuckets   []string      `yaml:"allowed_buckets"   json:"allowed_buckets"   validate:"omitempty,dive,oneof=second minute hour day"`
 	Jitter           time.Duration `yaml:"jitter"            json:"jitter"            validate:"gte=0"`
-	Retries          int           `yaml:"retries"           json:"retries"           validate:"required,gte=0"`
 	FailureThreshold int           `yaml:"failure_threshold" json:"failure_threshold" validate:"required,gte=1"`
 	Interval         time.Duration `yaml:"interval"          json:"interval"          validate:"required,gt=0ms"`
 	Timeout          time.Duration `yaml:"timeout"           json:"timeout"           validate:"required,gt=0ms"`
+	Retries          int           `yaml:"retries"           json:"retries"           validate:"required,gte=0"`
 	Enabled          bool          `yaml:"enabled"           json:"enabled"`
 }