feat: [FD-5561] implement FDv2 polling endpoint GET /sdk/poll (#701)

* Adding payload version and ID in the project table

* format:

* Update min payload version

* test fix

* feat: implement FDv2 polling endpoint GET /sdk/poll

Adds the FDv2 flag-delivery-v2 polling endpoint used by Go SDK v7.13+.
The basis param (the client's current payload version) is used only to
skip an unnecessary full transfer when the client is already up-to-date.
Stale clients always receive a full payload (xfer-full/cant-catchup) —
delta transfers are intentionally not supported, as that would require
persisting a change history which is overkill for a local dev server.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor: use SDK subsystems types in FDv2 polling

Replace locally-defined FDv2 wire-format types with the equivalent types
from go-server-sdk/v7/subsystems: RawEvent, PollingPayload, PutObject,
ServerIntent, Selector, and the IntentTransferFull/IntentNone/FlagKind
constants. The three reason strings (up-to-date, cant-catchup,
payload-missing) have no SDK equivalents and remain as local constants.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Unit tests and fixes

* fix

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hkotian

internal/dev_server/sdk/fdv2.go

@@ -0,0 +1,136 @@
+package sdk
+
+import (
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/launchdarkly/go-server-sdk/v7/subsystems"
+	"github.com/launchdarkly/ldcli/internal/dev_server/model"
+)
+
+const (
+	fdv2ReasonUpToDate       = "up-to-date"
+	fdv2ReasonCantCatchup    = "cant-catchup"
+	fdv2ReasonPayloadMissing = "payload-missing"
+)
+
+// parseBasis extracts the payload ID and version from a basis state string of the
+// form "(p:<payloadId>:<version>)". Returns ("", 0) if the string is absent or unparseable.
+//
+// Note: in production LD selectors the payload ID is an opaque server-assigned value.
+// The dev server uses the project key as the payload ID (see makePayloadTransferredEvent).
+// This is a dev-server-specific convention and should not be assumed elsewhere.
+func parseBasis(basis string) (string, int) {
+	if !strings.HasPrefix(basis, "(p:") || !strings.HasSuffix(basis, ")") {
+		return "", 0
+	}
+	// Strip the "(p:" prefix and ")" suffix to get "<payloadId>:<version>".
+	inner := basis[3 : len(basis)-1]
+	lastColon := strings.LastIndex(inner, ":")
+	if lastColon == -1 {
+		return "", 0
+	}
+	version, err := strconv.Atoi(inner[lastColon+1:])
+	if err != nil || version < 0 {
+		return "", 0
+	}
+	return inner[:lastColon], version
+}
+
+// buildPollResponse constructs the FDv2 polling response.
+//
+// payloadID is the stable identifier for this payload (the project key).
+// currentVersion is the project's current PayloadVersion.
+// flags is the current flag state with overrides applied.
+// basis is the raw ?basis query param from the SDK (empty string = no basis provided).
+//
+// Delta transfers are not supported: stale clients always receive a full payload.
+// Tracking the change history required for deltas is overkill for a local dev server.
+func buildPollResponse(payloadID string, currentVersion int, flags model.FlagsState, basis string) (subsystems.PollingPayload, error) {
+	basisPayloadID, basisVersion := parseBasis(basis)
+	switch {
+	case basisVersion == 0:
+		return buildFullTransferResponse(payloadID, currentVersion, flags, fdv2ReasonPayloadMissing)
+	case basisPayloadID == payloadID && basisVersion == currentVersion:
+		event, err := makeServerIntentEvent(payloadID, currentVersion, subsystems.IntentNone, fdv2ReasonUpToDate)
+		if err != nil {
+			return subsystems.PollingPayload{}, err
+		}
+		return subsystems.PollingPayload{Events: []subsystems.RawEvent{event}}, nil
+	default:
+		// Payload ID mismatch, stale version, or version ahead of current (e.g. project recreated):
+		// we can't compute a delta — send the full payload.
+		return buildFullTransferResponse(payloadID, currentVersion, flags, fdv2ReasonCantCatchup)
+	}
+}
+
+func buildFullTransferResponse(payloadID string, version int, flags model.FlagsState, reason string) (subsystems.PollingPayload, error) {
+	intentEvent, err := makeServerIntentEvent(payloadID, version, subsystems.IntentTransferFull, reason)
+	if err != nil {
+		return subsystems.PollingPayload{}, err
+	}
+	events := []subsystems.RawEvent{intentEvent}
+
+	for key, flagState := range flags {
+		event, err := makePutObjectEvent(version, key, flagState)
+		if err != nil {
+			return subsystems.PollingPayload{}, err
+		}
+		events = append(events, event)
+	}
+
+	transferredEvent, err := makePayloadTransferredEvent(payloadID, version)
+	if err != nil {
+		return subsystems.PollingPayload{}, err
+	}
+	events = append(events, transferredEvent)
+
+	return subsystems.PollingPayload{Events: events}, nil
+}
+
+func makeServerIntentEvent(payloadID string, target int, intentCode subsystems.IntentCode, reason string) (subsystems.RawEvent, error) {
+	data, err := json.Marshal(subsystems.ServerIntent{
+		Payload: subsystems.Payload{
+			ID:     payloadID,
+			Target: target,
+			Code:   intentCode,
+			Reason: reason,
+		},
+	})
+	if err != nil {
+		return subsystems.RawEvent{}, err
+	}
+	return subsystems.RawEvent{Name: subsystems.EventServerIntent, Data: data}, nil
+}
+
+func makePutObjectEvent(version int, key string, flagState model.FlagState) (subsystems.RawEvent, error) {
+	object, err := json.Marshal(serverFlagFromFlagState(key, flagState))
+	if err != nil {
+		return subsystems.RawEvent{}, err
+	}
+	data, err := json.Marshal(subsystems.PutObject{
+		Version: version,
+		Kind:    subsystems.FlagKind,
+		Key:     key,
+		Object:  object,
+	})
+	if err != nil {
+		return subsystems.RawEvent{}, err
+	}
+	return subsystems.RawEvent{Name: subsystems.EventPutObject, Data: data}, nil
+}
+
+func makePayloadTransferredEvent(payloadID string, version int) (subsystems.RawEvent, error) {
+	// The selector state is synthetic and dev-server-specific: the dev server uses the
+	// project key as the payload ID rather than a server-assigned opaque value. The SDK
+	// echoes this selector back as ?basis on subsequent polls, where parseBasisVersion
+	// extracts the version from it.
+	selector := subsystems.NewSelector(fmt.Sprintf("(p:%s:%d)", payloadID, version), version)
+	data, err := json.Marshal(selector)
+	if err != nil {
+		return subsystems.RawEvent{}, err
+	}
+	return subsystems.RawEvent{Name: subsystems.EventPayloadTransferred, Data: data}, nil
+}

internal/dev_server/sdk/fdv2_test.go

@@ -0,0 +1,257 @@
+package sdk
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/gorilla/mux"
+	"github.com/launchdarkly/go-sdk-common/v3/ldcontext"
+	"github.com/launchdarkly/go-sdk-common/v3/ldvalue"
+	"github.com/launchdarkly/go-server-sdk/v7/subsystems"
+	"github.com/launchdarkly/ldcli/internal/dev_server/model"
+	"github.com/launchdarkly/ldcli/internal/dev_server/model/mocks"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/mock/gomock"
+)
+
+func TestParseBasis(t *testing.T) {
+	tests := []struct {
+		basis           string
+		expectedID      string
+		expectedVersion int
+	}{
+		{"", "", 0},
+		{"(p:my-project:5)", "my-project", 5},
+		{"(p:my-project:1)", "my-project", 1},
+		{"(p:complex:key:with:colons:99)", "complex:key:with:colons", 99},
+		{"not-valid", "", 0},
+		{"(p:no-version)", "", 0},
+		{"(p:negative:-1)", "", 0},
+		{"(p:nan:abc)", "", 0},
+	}
+
+	for _, tt := range tests {
+		t.Run(fmt.Sprintf("basis=%q", tt.basis), func(t *testing.T) {
+			id, version := parseBasis(tt.basis)
+			assert.Equal(t, tt.expectedID, id)
+			assert.Equal(t, tt.expectedVersion, version)
+		})
+	}
+}
+
+func TestBuildPollResponse(t *testing.T) {
+	payloadID := "test-project"
+	currentVersion := 5
+	flags := model.FlagsState{
+		"flag-1": model.FlagState{Value: ldvalue.Bool(true), Version: 2},
+	}
+
+	t.Run("no basis sends xfer-full with payload-missing", func(t *testing.T) {
+		resp, err := buildPollResponse(payloadID, currentVersion, flags, "")
+		require.NoError(t, err)
+
+		require.GreaterOrEqual(t, len(resp.Events), 3) // server-intent + put-objects + payload-transferred
+
+		assertServerIntentEvent(t, resp.Events[0], payloadID, currentVersion, subsystems.IntentTransferFull, fdv2ReasonPayloadMissing)
+		assertPayloadTransferredEvent(t, resp.Events[len(resp.Events)-1], payloadID, currentVersion)
+	})
+
+	t.Run("up-to-date basis sends none with up-to-date", func(t *testing.T) {
+		basis := fmt.Sprintf("(p:%s:%d)", payloadID, currentVersion)
+		resp, err := buildPollResponse(payloadID, currentVersion, flags, basis)
+		require.NoError(t, err)
+
+		require.Len(t, resp.Events, 1)
+		assertServerIntentEvent(t, resp.Events[0], payloadID, currentVersion, subsystems.IntentNone, fdv2ReasonUpToDate)
+	})
+
+	t.Run("basis ahead of current version sends full transfer (e.g. project recreated)", func(t *testing.T) {
+		basis := fmt.Sprintf("(p:%s:%d)", payloadID, currentVersion+10)
+		resp, err := buildPollResponse(payloadID, currentVersion, flags, basis)
+		require.NoError(t, err)
+
+		require.GreaterOrEqual(t, len(resp.Events), 3)
+		assertServerIntentEvent(t, resp.Events[0], payloadID, currentVersion, subsystems.IntentTransferFull, fdv2ReasonCantCatchup)
+		assertPayloadTransferredEvent(t, resp.Events[len(resp.Events)-1], payloadID, currentVersion)
+	})
+
+	t.Run("stale basis sends xfer-full with cant-catchup", func(t *testing.T) {
+		basis := fmt.Sprintf("(p:%s:%d)", payloadID, currentVersion-1)
+		resp, err := buildPollResponse(payloadID, currentVersion, flags, basis)
+		require.NoError(t, err)
+
+		require.GreaterOrEqual(t, len(resp.Events), 3)
+		assertServerIntentEvent(t, resp.Events[0], payloadID, currentVersion, subsystems.IntentTransferFull, fdv2ReasonCantCatchup)
+		assertPayloadTransferredEvent(t, resp.Events[len(resp.Events)-1], payloadID, currentVersion)
+	})
+
+	t.Run("basis with wrong payload ID sends xfer-full", func(t *testing.T) {
+		basis := fmt.Sprintf("(p:%s:%d)", "other-project", currentVersion)
+		resp, err := buildPollResponse(payloadID, currentVersion, flags, basis)
+		require.NoError(t, err)
+
+		require.GreaterOrEqual(t, len(resp.Events), 3)
+		assertServerIntentEvent(t, resp.Events[0], payloadID, currentVersion, subsystems.IntentTransferFull, fdv2ReasonCantCatchup)
+		assertPayloadTransferredEvent(t, resp.Events[len(resp.Events)-1], payloadID, currentVersion)
+	})
+
+	t.Run("full transfer includes a put-object for each flag", func(t *testing.T) {
+		multiFlags := model.FlagsState{
+			"flag-a": model.FlagState{Value: ldvalue.Bool(true), Version: 1},
+			"flag-b": model.FlagState{Value: ldvalue.String("hello"), Version: 2},
+		}
+		resp, err := buildPollResponse(payloadID, currentVersion, multiFlags, "")
+		require.NoError(t, err)
+
+		// server-intent + 2 put-objects + payload-transferred
+		assert.Len(t, resp.Events, 4)
+		putKeys := make(map[string]bool)
+		for _, event := range resp.Events {
+			if event.Name == subsystems.EventPutObject {
+				var put subsystems.PutObject
+				require.NoError(t, json.Unmarshal(event.Data, &put))
+				putKeys[put.Key] = true
+				assert.Equal(t, currentVersion, put.Version)
+				assert.Equal(t, subsystems.FlagKind, put.Kind)
+			}
+		}
+		assert.True(t, putKeys["flag-a"])
+		assert.True(t, putKeys["flag-b"])
+	})
+}
+
+func TestPollV2Handler(t *testing.T) {
+	mockController := gomock.NewController(t)
+	store := mocks.NewMockStore(mockController)
+	observers := model.NewObservers()
+
+	router := mux.NewRouter()
+	router.Use(model.ObserversMiddleware(observers))
+	router.Use(model.StoreMiddleware(store))
+	BindRoutes(router)
+
+	project := &model.Project{
+		Key:                  exampleProjectKey,
+		SourceEnvironmentKey: "my-environment",
+		Context:              ldcontext.Context{},
+		LastSyncTime:         time.Unix(0, 0),
+		AllFlagsState: model.FlagsState{
+			"flag-1": model.FlagState{Value: ldvalue.Bool(true), Version: 1},
+		},
+		AvailableVariations: nil,
+		PayloadVersion:      3,
+	}
+
+	t.Run("no basis returns full payload", func(t *testing.T) {
+		store.EXPECT().GetDevProject(gomock.Any(), exampleProjectKey).Return(project, nil)
+		store.EXPECT().GetOverridesForProject(gomock.Any(), exampleProjectKey).Return(nil, nil)
+
+		req := httptest.NewRequest(http.MethodGet, "/sdk/poll", nil)
+		req.Header.Set("Authorization", exampleProjectKey)
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+
+		require.Equal(t, http.StatusOK, rec.Code)
+		assert.Equal(t, "application/json", rec.Header().Get("Content-Type"))
+
+		var resp subsystems.PollingPayload
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+		require.GreaterOrEqual(t, len(resp.Events), 3)
+		assertServerIntentEvent(t, resp.Events[0], exampleProjectKey, 3, subsystems.IntentTransferFull, fdv2ReasonPayloadMissing)
+		assertPayloadTransferredEvent(t, resp.Events[len(resp.Events)-1], exampleProjectKey, 3)
+	})
+
+	t.Run("up-to-date basis returns none intent", func(t *testing.T) {
+		store.EXPECT().GetDevProject(gomock.Any(), exampleProjectKey).Return(project, nil)
+		store.EXPECT().GetOverridesForProject(gomock.Any(), exampleProjectKey).Return(nil, nil)
+
+		basisState := fmt.Sprintf("(p:%s:%d)", exampleProjectKey, project.PayloadVersion)
+		req := httptest.NewRequest(http.MethodGet, "/sdk/poll?basis="+basisState, nil)
+		req.Header.Set("Authorization", exampleProjectKey)
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+
+		require.Equal(t, http.StatusOK, rec.Code)
+
+		var resp subsystems.PollingPayload
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+		require.Len(t, resp.Events, 1)
+		assertServerIntentEvent(t, resp.Events[0], exampleProjectKey, 3, subsystems.IntentNone, fdv2ReasonUpToDate)
+	})
+
+	t.Run("url-encoded basis is decoded correctly", func(t *testing.T) {
+		store.EXPECT().GetDevProject(gomock.Any(), exampleProjectKey).Return(project, nil)
+		store.EXPECT().GetOverridesForProject(gomock.Any(), exampleProjectKey).Return(nil, nil)
+
+		basisState := fmt.Sprintf("(p:%s:%d)", exampleProjectKey, project.PayloadVersion)
+		req := httptest.NewRequest(http.MethodGet, "/sdk/poll?basis="+url.QueryEscape(basisState), nil)
+		req.Header.Set("Authorization", exampleProjectKey)
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+
+		require.Equal(t, http.StatusOK, rec.Code)
+
+		var resp subsystems.PollingPayload
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+		require.Len(t, resp.Events, 1)
+		assertServerIntentEvent(t, resp.Events[0], exampleProjectKey, 3, subsystems.IntentNone, fdv2ReasonUpToDate)
+	})
+
+	t.Run("stale basis returns full payload with cant-catchup", func(t *testing.T) {
+		store.EXPECT().GetDevProject(gomock.Any(), exampleProjectKey).Return(project, nil)
+		store.EXPECT().GetOverridesForProject(gomock.Any(), exampleProjectKey).Return(nil, nil)
+
+		basisState := fmt.Sprintf("(p:%s:%d)", exampleProjectKey, project.PayloadVersion-1)
+		req := httptest.NewRequest(http.MethodGet, "/sdk/poll?basis="+basisState, nil)
+		req.Header.Set("Authorization", exampleProjectKey)
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+
+		require.Equal(t, http.StatusOK, rec.Code)
+
+		var resp subsystems.PollingPayload
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+		require.GreaterOrEqual(t, len(resp.Events), 3)
+		assertServerIntentEvent(t, resp.Events[0], exampleProjectKey, 3, subsystems.IntentTransferFull, fdv2ReasonCantCatchup)
+		assertPayloadTransferredEvent(t, resp.Events[len(resp.Events)-1], exampleProjectKey, 3)
+	})
+
+	t.Run("unknown project returns 404", func(t *testing.T) {
+		store.EXPECT().GetDevProject(gomock.Any(), exampleProjectKey).Return(nil, model.NewErrNotFound("project", exampleProjectKey))
+
+		req := httptest.NewRequest(http.MethodGet, "/sdk/poll", nil)
+		req.Header.Set("Authorization", exampleProjectKey)
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+
+		assert.Equal(t, http.StatusNotFound, rec.Code)
+	})
+}
+
+// assertServerIntentEvent unmarshals a server-intent event and checks its fields.
+func assertServerIntentEvent(t *testing.T, event subsystems.RawEvent, payloadID string, target int, intentCode subsystems.IntentCode, reason string) {
+	t.Helper()
+	assert.Equal(t, subsystems.EventServerIntent, event.Name)
+	var data subsystems.ServerIntent
+	require.NoError(t, json.Unmarshal(event.Data, &data))
+	assert.Equal(t, payloadID, data.Payload.ID)
+	assert.Equal(t, target, data.Payload.Target)
+	assert.Equal(t, intentCode, data.Payload.Code)
+	assert.Equal(t, reason, data.Payload.Reason)
+}
+
+// assertPayloadTransferredEvent unmarshals a payload-transferred event and checks its fields.
+func assertPayloadTransferredEvent(t *testing.T, event subsystems.RawEvent, payloadID string, version int) {
+	t.Helper()
+	assert.Equal(t, subsystems.EventPayloadTransferred, event.Name)
+	var data subsystems.Selector
+	require.NoError(t, json.Unmarshal(event.Data, &data))
+	assert.Equal(t, version, data.Version())
+	assert.Equal(t, fmt.Sprintf("(p:%s:%d)", payloadID, version), data.State())
+}