feat: bee node status and metrics (work in progress)

openapi/SwarmCommon.yaml

@@ -503,6 +503,25 @@ components:
           type: boolean
         swapEnabled:
           type: boolean
+        beeStatus:
+          type: string
+          description: >
+            Current node startup or runtime phase. The zero/unknown value means
+            the phase has not been reported yet.
+            * `starting`
+            * `waiting_chain_sync`
+            * `starting_chequebook`
+            * `opening_localstore`
+            * `resetting_reserve`
+            * `loading_postage_snapshot`
+            * `syncing_postage`
+            * `updating_stake_height`
+            * `warming_up`
+            * `counting_reserve`
+            * `evicting_reserve`
+            * `syncing_reserve`
+            * `ready`
+            * `unknown`
 
     HealthStatus:
       type: object
@@ -521,6 +540,9 @@ components:
           type: string
           default: "0.0.0"
           description: The default value is set in case the bee binary was not build correctly.
+        beeStatus:
+          type: string
+          description: Current node startup or runtime phase. See Node.beeStatus.
 
     PostageBatch:
       type: object
@@ -971,6 +993,9 @@ components:
           type: integer
         isWarmingUp:
           type: boolean
+        beeStatus:
+          type: string
+          description: Current node startup or runtime phase. See Node.beeStatus.
 
     StatusPeersResponse:
       type: object

pkg/api/api.go

@@ -226,6 +226,12 @@ type Service struct {
 
 	statusService *status.Service
 	isWarmingUp   bool
+	beeStatus     BeeStatus
+}
+
+type BeeStatus interface {
+	StatusCode() int32
+	StatusString() string
 }
 
 func (s *Service) SetP2P(p2p p2p.DebugService) {
@@ -396,6 +402,26 @@ func (s *Service) SetIsWarmingUp(v bool) {
 	}
 }
 
+func (s *Service) SetBeeStatus(status BeeStatus) {
+	if s != nil {
+		s.beeStatus = status
+	}
+}
+
+func (s *Service) BeeStatusCode() int32 {
+	if s == nil || s.beeStatus == nil {
+		return 0
+	}
+	return s.beeStatus.StatusCode()
+}
+
+func (s *Service) BeeStatusString() string {
+	if s == nil || s.beeStatus == nil {
+		return "unknown"
+	}
+	return s.beeStatus.StatusString()
+}
+
 // Close hangs up running websockets on shutdown.
 func (s *Service) Close() error {
 	s.logger.Info("api shutting down")

pkg/api/api_test.go

@@ -137,6 +137,7 @@ type testServerOptions struct {
 	ChequebookDisabled  bool
 	SwapDisabled        bool
 	Erc20ServiceNil     bool
+	BeeStatus           api.BeeStatus
 }
 
 func newTestServer(t *testing.T, o testServerOptions) (*http.Client, *websocket.Conn, string, *chanStorer) {
@@ -231,6 +232,7 @@ func newTestServer(t *testing.T, o testServerOptions) (*http.Client, *websocket.
 
 	s.SetSwarmAddress(&o.Overlay)
 	s.SetProbe(o.Probe)
+	s.SetBeeStatus(o.BeeStatus)
 
 	tracer := o.Tracer
 	if tracer == nil {

pkg/api/bee_status_test.go

@@ -0,0 +1,131 @@
+// Copyright 2026 The Swarm Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package api_test
+
+import (
+	"crypto/ecdsa"
+	"net/http"
+	"testing"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethersphere/bee/v2"
+	"github.com/ethersphere/bee/v2/pkg/api"
+	"github.com/ethersphere/bee/v2/pkg/jsonhttp"
+	"github.com/ethersphere/bee/v2/pkg/jsonhttp/jsonhttptest"
+	"github.com/ethersphere/bee/v2/pkg/log"
+)
+
+type testBeeStatus struct {
+	code int32
+	name string
+}
+
+func (t testBeeStatus) StatusCode() int32    { return t.code }
+func (t testBeeStatus) StatusString() string { return t.name }
+
+func TestSetBeeStatus(t *testing.T) {
+	t.Parallel()
+
+	var unset *api.Service
+	if unset.BeeStatusCode() != 0 || unset.BeeStatusString() != "unknown" {
+		t.Fatal("nil service must report unknown status")
+	}
+
+	s := api.New(
+		ecdsa.PublicKey{},
+		ecdsa.PublicKey{},
+		common.Address{},
+		nil,
+		log.Noop,
+		nil,
+		nil,
+		api.FullMode,
+		false,
+		false,
+		nil,
+		nil,
+		nil,
+	)
+
+	if s.BeeStatusString() != "unknown" {
+		t.Fatalf("got %q, want unknown", s.BeeStatusString())
+	}
+
+	s.SetBeeStatus(testBeeStatus{code: 4, name: "opening_localstore"})
+	if s.BeeStatusCode() != 4 {
+		t.Fatalf("got code %d, want 4", s.BeeStatusCode())
+	}
+	if s.BeeStatusString() != "opening_localstore" {
+		t.Fatalf("got %q, want opening_localstore", s.BeeStatusString())
+	}
+}
+
+func TestBeeStatusEndpoints(t *testing.T) {
+	t.Parallel()
+
+	status := testBeeStatus{code: 4, name: "opening_localstore"}
+	probe := api.NewProbe()
+	probe.SetHealthy(api.ProbeStatusOK)
+
+	t.Run("available endpoints", func(t *testing.T) {
+		t.Parallel()
+
+		testServer, _, _, _ := newTestServer(t, testServerOptions{
+			BeeStatus: status,
+			Probe:     probe,
+		})
+
+		jsonhttptest.Request(t, testServer, http.MethodGet, "/node", http.StatusOK,
+			jsonhttptest.WithExpectedJSONResponse(api.NodeResponse{
+				BeeMode:           api.FullMode.String(),
+				ChequebookEnabled: true,
+				SwapEnabled:       true,
+				BeeStatus:         "opening_localstore",
+			}),
+		)
+		jsonhttptest.Request(t, testServer, http.MethodGet, "/health", http.StatusOK,
+			jsonhttptest.WithExpectedJSONResponse(api.HealthStatusResponse{
+				Status:     "ok",
+				Version:    bee.Version,
+				APIVersion: api.Version,
+				BeeStatus:  "opening_localstore",
+			}),
+		)
+	})
+
+	t.Run("status and reservestate before full api", func(t *testing.T) {
+		t.Parallel()
+
+		testServer, _, _, _ := newTestServer(t, testServerOptions{
+			BeeStatus:       status,
+			FullAPIDisabled: true,
+		})
+
+		jsonhttptest.Request(t, testServer, http.MethodGet, "/status", http.StatusOK,
+			jsonhttptest.WithExpectedJSONResponse(api.StatusSnapshotResponse{
+				Proximity: 256,
+				BeeMode:   api.FullMode.String(),
+				BeeStatus: "opening_localstore",
+			}),
+		)
+		jsonhttptest.Request(t, testServer, http.MethodGet, "/reservestate", http.StatusOK)
+	})
+
+	t.Run("unavailable message", func(t *testing.T) {
+		t.Parallel()
+
+		testServer, _, _, _ := newTestServer(t, testServerOptions{
+			BeeStatus:       status,
+			FullAPIDisabled: true,
+		})
+
+		jsonhttptest.Request(t, testServer, http.MethodGet, "/bytes/00", http.StatusServiceUnavailable,
+			jsonhttptest.WithExpectedJSONResponse(jsonhttp.StatusResponse{
+				Code:    http.StatusServiceUnavailable,
+				Message: "node is not ready: opening_localstore",
+			}),
+		)
+	})
+}

pkg/api/health.go

@@ -15,6 +15,7 @@ type healthStatusResponse struct {
 	Status     string `json:"status"`
 	Version    string `json:"version"`
 	APIVersion string `json:"apiVersion"`
+	BeeStatus  string `json:"beeStatus"`
 }
 
 func (s *Service) healthHandler(w http.ResponseWriter, _ *http.Request) {
@@ -23,5 +24,6 @@ func (s *Service) healthHandler(w http.ResponseWriter, _ *http.Request) {
 		Status:     status.String(),
 		Version:    bee.Version,
 		APIVersion: Version,
+		BeeStatus:  s.BeeStatusString(),
 	})
 }

pkg/api/health_test.go

@@ -26,6 +26,7 @@ func TestHealth(t *testing.T) {
 			Status:     "nok",
 			Version:    bee.Version,
 			APIVersion: api.Version,
+			BeeStatus:  "unknown",
 		}))
 	})
 
@@ -42,6 +43,7 @@ func TestHealth(t *testing.T) {
 			Status:     "nok",
 			Version:    bee.Version,
 			APIVersion: api.Version,
+			BeeStatus:  "unknown",
 		}))
 
 		// When we set health probe to OK it should indicate that node is healthy
@@ -50,6 +52,7 @@ func TestHealth(t *testing.T) {
 			Status:     "ok",
 			Version:    bee.Version,
 			APIVersion: api.Version,
+			BeeStatus:  "unknown",
 		}))
 
 		// When we set health probe to NOK it should indicate that node is not healthy
@@ -58,6 +61,7 @@ func TestHealth(t *testing.T) {
 			Status:     "nok",
 			Version:    bee.Version,
 			APIVersion: api.Version,
+			BeeStatus:  "unknown",
 		}))
 	})
 }

pkg/api/node.go

@@ -23,6 +23,7 @@ type nodeResponse struct {
 	BeeMode           string `json:"beeMode"`
 	ChequebookEnabled bool   `json:"chequebookEnabled"`
 	SwapEnabled       bool   `json:"swapEnabled"`
+	BeeStatus         string `json:"beeStatus"`
 }
 
 func (b BeeNodeMode) String() string {
@@ -43,5 +44,6 @@ func (s *Service) nodeGetHandler(w http.ResponseWriter, _ *http.Request) {
 		BeeMode:           s.beeMode.String(),
 		ChequebookEnabled: s.chequebookEnabled,
 		SwapEnabled:       s.swapEnabled,
+		BeeStatus:         s.BeeStatusString(),
 	})
 }

pkg/api/p2p_test.go

@@ -69,6 +69,7 @@ func TestAddresses(t *testing.T) {
 			BeeMode:           api.FullMode.String(),
 			ChequebookEnabled: true,
 			SwapEnabled:       true,
+			BeeStatus:         "unknown",
 		}),
 	)
 }

pkg/api/postage.go

@@ -431,20 +431,26 @@ type chainStateResponse struct {
 func (s *Service) reserveStateHandler(w http.ResponseWriter, _ *http.Request) {
 	logger := s.logger.WithName("get_reservestate").Build()
 
-	commitment, err := s.batchStore.Commitment()
-	if err != nil {
-		logger.Debug("batch store commitment calculation failed", "error", err)
-		logger.Error(nil, "batch store commitment calculation failed")
-		jsonhttp.InternalServerError(w, "unable to calculate commitment")
-		return
+	resp := reserveStateResponse{}
+
+	if s.batchStore != nil {
+		commitment, err := s.batchStore.Commitment()
+		if err != nil {
+			logger.Debug("batch store commitment calculation failed", "error", err)
+			logger.Error(nil, "batch store commitment calculation failed")
+			jsonhttp.InternalServerError(w, "unable to calculate commitment")
+			return
+		}
+		resp.Radius = s.batchStore.Radius()
+		resp.Commitment = commitment
 	}
 
-	jsonhttp.OK(w, reserveStateResponse{
-		Radius:                  s.batchStore.Radius(),
-		StorageRadius:           s.storer.StorageRadius(),
-		Commitment:              commitment,
-		ReserveCapacityDoubling: s.storer.CapacityDoubling(),
-	})
+	if s.storer != nil {
+		resp.StorageRadius = s.storer.StorageRadius()
+		resp.ReserveCapacityDoubling = s.storer.CapacityDoubling()
+	}
+
+	jsonhttp.OK(w, resp)
 }
 
 // chainStateHandler returns the current chain state.

pkg/api/readiness.go

@@ -19,12 +19,14 @@ func (s *Service) readinessHandler(w http.ResponseWriter, _ *http.Request) {
 			Status:     "ready",
 			Version:    bee.Version,
 			APIVersion: Version,
+			BeeStatus:  s.BeeStatusString(),
 		})
 	} else {
 		jsonhttp.BadRequest(w, ReadyStatusResponse{
 			Status:     "notReady",
 			Version:    bee.Version,
 			APIVersion: Version,
+			BeeStatus:  s.BeeStatusString(),
 		})
 	}
 }

pkg/api/readiness_test.go

@@ -42,6 +42,7 @@ func TestReadiness(t *testing.T) {
 				Status:     "ready",
 				Version:    "-dev",
 				APIVersion: "0.0.0",
+				BeeStatus:  "unknown",
 			}))
 
 		// When we set readiness probe to NOK it should indicate that API is not ready
@@ -51,6 +52,7 @@ func TestReadiness(t *testing.T) {
 				Status:     "notReady",
 				Version:    "-dev",
 				APIVersion: "0.0.0",
+				BeeStatus:  "unknown",
 			}))
 	})
 }