Experimental API example integration

Author: stephanos

Makefile

@@ -47,8 +47,14 @@ VISIBILITY_DB ?= temporal_visibility
 # The `disable_grpc_modules` build tag excludes gRPC dependencies from cloud.google.com/go/storage,
 # reducing binary size by 16MB since we only use the REST client (storage.NewClient), not the
 # gRPC client (storage.NewGRPCClient). Related issue: https://github.com/googleapis/google-cloud-go/issues/12343
+#
+# The `experimental` tag is added to ALL_TEST_TAGS (not ALL_BUILD_TAGS) so
+# the production binary is built without it but every test invocation gets
+# it by default. This keeps the test/dev path realistic (variants pickable
+# per cluster via dynconfig) while ensuring `make build` of temporal-server
+# never accidentally pulls in experimental code or its api-go modules.
 ALL_BUILD_TAGS := disable_grpc_modules,$(BUILD_TAG)
-ALL_TEST_TAGS := $(ALL_BUILD_TAGS),test_dep,$(TEST_TAG)
+ALL_TEST_TAGS := $(ALL_BUILD_TAGS),test_dep,experimental,$(TEST_TAG)
 BUILD_TAG_FLAG := -tags $(ALL_BUILD_TAGS)
 TEST_TAG_FLAG := -tags $(ALL_TEST_TAGS)
 

common/dynamicconfig/constants.go

@@ -99,6 +99,26 @@ values in system search attributes.`,
 query.`,
 	)
 
+	// FrontendAPIVariant selects which frontend API variant the
+	// frontend exposes at startup. Empty (default) registers stable
+	// WorkflowService only. A non-empty value (e.g. "ping", "tinker") looks
+	// up the named variant in the experimental registry and registers it
+	// IN PLACE OF stable WorkflowService at the same wire path; the variant
+	// delegates stable methods to the existing stable handler. Toggling
+	// requires a frontend restart.
+	//
+	// A variant name is only resolvable if the corresponding build tag was
+	// set (e.g. -tags experimental). With no tag, the registry is
+	// empty and any non-empty value here causes Start() to log Fatal —
+	// production binaries cannot accidentally expose experimental surface.
+	FrontendAPIVariant = NewGlobalStringSetting(
+		"frontend.apiVariant",
+		"",
+		`FrontendAPIVariant selects which frontend API variant the
+frontend exposes. Empty = stable only. See service/frontend/services/
+for the list of supported variants in this build.`,
+	)
+
 	HistoryArchivalState = NewGlobalStringSetting(
 		"system.historyArchivalState",
 		"", // actual default is from static config

go.mod

@@ -46,6 +46,7 @@ require (
 	github.com/robfig/cron/v3 v3.0.1
 	github.com/sony/gobreaker v1.0.0
 	github.com/stretchr/testify v1.11.1
+	github.com/temporalio/api-go/experimental/example v0.0.0-20260425220524-eb1c7feb8022
 	github.com/temporalio/ringpop-go v0.0.0-20250130211428-b97329e994f7
 	github.com/temporalio/sqlparser v0.0.0-20231115171017-f4060bcfa6cb
 	github.com/temporalio/tchannel-go v1.22.1-0.20260129151045-8706a1ab5f61

go.sum

@@ -394,6 +394,8 @@ github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXl
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/temporalio/api-go/experimental/example v0.0.0-20260425220524-eb1c7feb8022 h1:C3guzElkL2xWFKhLoXw9TJn6OAh8XjbMona2cJo3rhs=
+github.com/temporalio/api-go/experimental/example v0.0.0-20260425220524-eb1c7feb8022/go.mod h1:51vB7ml3vLZ4cxGSW9JQVjbTdmWeZd4igRb2kq7kdt4=
 github.com/temporalio/ringpop-go v0.0.0-20250130211428-b97329e994f7 h1:lEebX/hZss+TSH3EBwhztnBavJVj7pWGJOH8UgKHS0w=
 github.com/temporalio/ringpop-go v0.0.0-20250130211428-b97329e994f7/go.mod h1:RE+CHmY+kOZQk47AQaVzwrGmxpflnLgTd6EOK0853j4=
 github.com/temporalio/sqlparser v0.0.0-20231115171017-f4060bcfa6cb h1:YzHH/U/dN7vMP+glybzcXRTczTrgfdRisNTzAj7La04=

service/frontend/service.go

@@ -6,9 +6,6 @@ import (
 	"sync"
 	"time"
 
-	"go.temporal.io/api/operatorservice/v1"
-	"go.temporal.io/api/workflowservice/v1"
-	"go.temporal.io/server/api/adminservice/v1"
 	"go.temporal.io/server/chasm/lib/activity"
 	chasmnexus "go.temporal.io/server/chasm/lib/nexusoperation"
 	"go.temporal.io/server/common/dynamicconfig"
@@ -20,6 +17,7 @@ import (
 	"go.temporal.io/server/common/retrypolicy"
 	"go.temporal.io/server/components/callbacks"
 	"go.temporal.io/server/components/nexusoperations"
+	"go.temporal.io/server/service/frontend/services"
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/health"
 	healthpb "google.golang.org/grpc/health/grpc_health_v1"
@@ -232,6 +230,10 @@ type Config struct {
 	HTTPAllowedHosts   dynamicconfig.TypedPropertyFn[*regexp.Regexp]
 	AllowedExperiments dynamicconfig.TypedPropertyFnWithNamespaceFilter[[]string]
 
+	// APIVariant selects which frontend API variant the
+	// frontend exposes at startup. See service/frontend/services/.
+	APIVariant dynamicconfig.StringPropertyFn
+
 	// CHASM archetypes
 	Activity *activity.Config
 }
@@ -400,6 +402,8 @@ func NewConfig(
 		HTTPAllowedHosts:   dynamicconfig.FrontendHTTPAllowedHosts.Get(dc),
 		AllowedExperiments: dynamicconfig.FrontendAllowedExperiments.Get(dc),
 
+		APIVariant: dynamicconfig.FrontendAPIVariant.Get(dc),
+
 		Activity: activity.ConfigProvider(dc),
 	}
 }
@@ -456,13 +460,19 @@ func NewService(
 }
 
 // Start starts the service
+
 func (s *Service) Start() {
 	s.logger.Info("frontend starting")
 
 	healthpb.RegisterHealthServer(s.server, s.healthServer)
-	workflowservice.RegisterWorkflowServiceServer(s.server, s.handler)
-	adminservice.RegisterAdminServiceServer(s.server, s.adminHandler)
-	operatorservice.RegisterOperatorServiceServer(s.server, s.operatorHandler)
+	services.Register(services.Registration{
+		Server:   s.server,
+		Workflow: s.handler,
+		Admin:    s.adminHandler,
+		Operator: s.operatorHandler,
+		Variant:  s.config.APIVariant(),
+		Logger:   s.logger,
+	})
 
 	reflection.Register(s.server)
 

service/frontend/services/api_example.go

@@ -0,0 +1,23 @@
+//go:build experimental
+
+package services
+
+import (
+	"context"
+
+	expexample "github.com/temporalio/api-go/experimental/example/workflowservice/v1"
+	"go.temporal.io/api/workflowservice/v1"
+	"google.golang.org/grpc"
+)
+
+type exampleHandler struct{}
+
+func (exampleHandler) Echo(_ context.Context, req *expexample.EchoRequest) (*expexample.EchoResponse, error) {
+	return &expexample.EchoResponse{Payload: req.GetPayload()}, nil
+}
+
+func init() {
+	register("example", variant{registerWorkflow: func(server *grpc.Server, workflow workflowservice.WorkflowServiceServer) {
+		registerServiceOverlay(server, workflowservice.WorkflowService_ServiceDesc, workflow, expexample.WorkflowService_ServiceDesc, exampleHandler{})
+	}})
+}

service/frontend/services/register.go

@@ -0,0 +1,84 @@
+package services
+
+import (
+	"go.temporal.io/api/operatorservice/v1"
+	"go.temporal.io/api/workflowservice/v1"
+	"go.temporal.io/server/api/adminservice/v1"
+	"go.temporal.io/server/common/log"
+	"go.temporal.io/server/common/log/tag"
+	"google.golang.org/grpc"
+)
+
+type variant struct {
+	registerWorkflow func(*grpc.Server, workflowservice.WorkflowServiceServer)
+	registerAdmin    func(*grpc.Server, adminservice.AdminServiceServer)
+	registerOperator func(*grpc.Server, operatorservice.OperatorServiceServer)
+}
+
+type Registration struct {
+	Server   *grpc.Server
+	Workflow workflowservice.WorkflowServiceServer
+	Admin    adminservice.AdminServiceServer
+	Operator operatorservice.OperatorServiceServer
+	Variant  string
+	Logger   log.Logger
+}
+
+// Register installs the stable frontend gRPC services, or an experimental
+// variant compiled into this binary.
+func Register(r Registration) {
+	if err := registryError(); err != nil {
+		r.Logger.Fatal("invalid experimental API registry", tag.Error(err))
+	}
+
+	selected := variant{}
+	if r.Variant == "" {
+		registerVariant(r, selected)
+		return
+	}
+
+	var ok bool
+	selected, ok = get(r.Variant)
+	if !ok {
+		r.Logger.Fatal(
+			"frontend.apiVariant set but variant not wired into this binary",
+			tag.NewStringTag("variant", r.Variant),
+			tag.NewStringsTag("compiled_in", names()),
+		)
+	}
+
+	registerVariant(r, selected)
+	r.Logger.Info("Experimental API variant active",
+		tag.NewStringTag("variant", r.Variant))
+}
+
+func registerVariant(r Registration, v variant) {
+	registerWorkflow := registerStableWorkflow
+	if v.registerWorkflow != nil {
+		registerWorkflow = v.registerWorkflow
+	}
+	registerAdmin := registerStableAdmin
+	if v.registerAdmin != nil {
+		registerAdmin = v.registerAdmin
+	}
+	registerOperator := registerStableOperator
+	if v.registerOperator != nil {
+		registerOperator = v.registerOperator
+	}
+
+	registerWorkflow(r.Server, r.Workflow)
+	registerAdmin(r.Server, r.Admin)
+	registerOperator(r.Server, r.Operator)
+}
+
+func registerStableWorkflow(server *grpc.Server, workflow workflowservice.WorkflowServiceServer) {
+	workflowservice.RegisterWorkflowServiceServer(server, workflow)
+}
+
+func registerStableAdmin(server *grpc.Server, admin adminservice.AdminServiceServer) {
+	adminservice.RegisterAdminServiceServer(server, admin)
+}
+
+func registerStableOperator(server *grpc.Server, operator operatorservice.OperatorServiceServer) {
+	operatorservice.RegisterOperatorServiceServer(server, operator)
+}

service/frontend/services/registry_default.go

@@ -0,0 +1,15 @@
+//go:build !experimental
+
+package services
+
+func get(string) (variant, bool) {
+	return variant{}, false
+}
+
+func names() []string {
+	return nil
+}
+
+func registryError() error {
+	return nil
+}

service/frontend/services/registry_experimental.go

@@ -0,0 +1,40 @@
+//go:build experimental
+
+package services
+
+import "fmt"
+
+var entries = map[string]variant{}
+var registryErr error
+
+func register(name string, v variant) {
+	if _, dup := entries[name]; dup {
+		registryErr = errorsJoin(registryErr, fmt.Errorf("duplicate registration for variant %s", name))
+		return
+	}
+	entries[name] = v
+}
+
+func get(name string) (variant, bool) {
+	v, ok := entries[name]
+	return v, ok
+}
+
+func names() []string {
+	out := make([]string, 0, len(entries))
+	for name := range entries {
+		out = append(out, name)
+	}
+	return out
+}
+
+func registryError() error {
+	return registryErr
+}
+
+func errorsJoin(current error, next error) error {
+	if current == nil {
+		return next
+	}
+	return fmt.Errorf("%w; %w", current, next)
+}

service/frontend/services/registry_test.go

@@ -0,0 +1,14 @@
+//go:build experimental
+
+package services
+
+import (
+	"sort"
+	"testing"
+)
+
+func TestRegisteredVariants(t *testing.T) {
+	names := names()
+	sort.Strings(names)
+	t.Logf("variants compiled in: %v", names)
+}