milvus-io--milvus/internal/streamingcoord/server/service/assignment.go

package service

import (
	"context"
	"sort"

	"github.com/cockroachdb/errors"
	"github.com/prometheus/client_golang/prometheus"
	"github.com/samber/lo"
	"google.golang.org/protobuf/proto"

	"github.com/milvus-io/milvus-proto/go-api/v3/commonpb"
	"github.com/milvus-io/milvus/internal/distributed/streaming"
	"github.com/milvus-io/milvus/internal/streamingcoord/server/balancer"
	"github.com/milvus-io/milvus/internal/streamingcoord/server/balancer/balance"
	"github.com/milvus-io/milvus/internal/streamingcoord/server/balancer/channel"
	"github.com/milvus-io/milvus/internal/streamingcoord/server/broadcaster/broadcast"
	"github.com/milvus-io/milvus/internal/streamingcoord/server/broadcaster/registry"
	"github.com/milvus-io/milvus/internal/streamingcoord/server/service/discover"
	"github.com/milvus-io/milvus/internal/util/streamingutil/status"
	"github.com/milvus-io/milvus/pkg/v3/metrics"
	"github.com/milvus-io/milvus/pkg/v3/mlog"
	"github.com/milvus-io/milvus/pkg/v3/proto/streamingpb"
	"github.com/milvus-io/milvus/pkg/v3/streaming/util/message"
	"github.com/milvus-io/milvus/pkg/v3/util/funcutil"
	"github.com/milvus-io/milvus/pkg/v3/util/paramtable"
	"github.com/milvus-io/milvus/pkg/v3/util/replicateutil"
)

var _ streamingpb.StreamingCoordAssignmentServiceServer = (*assignmentServiceImpl)(nil)

var (
	errReplicateConfigurationSame = errors.New("same replicate configuration")
	// errAssignmentDone is returned from a WatchChannelAssignments callback to
	// signal "target configuration reached, stop watching". The outer call site
	// identifies it via errors.Is and treats it as success.
	errAssignmentDone = errors.New("done")
)

// NewAssignmentService returns a new assignment service.
func NewAssignmentService() streamingpb.StreamingCoordAssignmentServiceServer {
	assignmentService := &assignmentServiceImpl{
		listenerTotal: metrics.StreamingCoordAssignmentListenerTotal.WithLabelValues(paramtable.GetStringNodeID()),
	}
	registry.RegisterAlterReplicateConfigV2AckCallback(assignmentService.alterReplicateConfiguration)
	return assignmentService
}

type AssignmentService interface {
	streamingpb.StreamingCoordAssignmentServiceServer
}

// assignmentServiceImpl is the implementation of the assignment service.
type assignmentServiceImpl struct {
	streamingpb.UnimplementedStreamingCoordAssignmentServiceServer

	listenerTotal prometheus.Gauge
}

// AssignmentDiscover watches the state of all log nodes.
func (s *assignmentServiceImpl) AssignmentDiscover(server streamingpb.StreamingCoordAssignmentService_AssignmentDiscoverServer) error {
	s.listenerTotal.Inc()
	defer s.listenerTotal.Dec()

	balancer, err := balance.GetWithContext(server.Context())
	if err != nil {
		return err
	}
	return discover.NewAssignmentDiscoverServer(balancer, server).Execute()
}

// UpdateReplicateConfiguration updates the replicate configuration to the milvus cluster.
func (s *assignmentServiceImpl) UpdateReplicateConfiguration(ctx context.Context, req *streamingpb.UpdateReplicateConfigurationRequest) (*streamingpb.UpdateReplicateConfigurationResponse, error) {
	config := req.GetConfiguration()

	mlog.Info(ctx, "UpdateReplicateConfiguration received",
		mlog.Bool("forcePromote", req.GetForcePromote()),
		replicateutil.ConfigLogField(config),
	)

	// Force promote path - promotes secondary cluster to standalone primary
	// Check this BEFORE normal validation since force promote requires empty config
	if req.GetForcePromote() {
		return s.handleForcePromote(ctx, config)
	}

	// check if the configuration is same.
	// so even if current cluster is not primary, we can still make a idempotent success result.
	if _, err := s.validateReplicateConfiguration(ctx, config); err != nil {
		if errors.Is(err, errReplicateConfigurationSame) {
			mlog.Info(ctx, "configuration is same, ignored")
			return &streamingpb.UpdateReplicateConfigurationResponse{}, nil
		}
		return nil, err
	}

	broadcaster, err := broadcast.StartBroadcastWithResourceKeys(ctx, message.NewExclusiveClusterResourceKey())
	if err != nil {
		if errors.Is(err, broadcast.ErrNotPrimary) {
			// current cluster is not primary, but we support an idempotent broadcast cross replication cluster.
			// For example, we have A/B/C three clusters, and A is primary in the replicating topology.
			// The milvus client can broadcast the UpdateReplicateConfiguration to all clusters,
			// if all clusters returne success, we can consider the UpdateReplicateConfiguration is successful and sync up between A/B/C.
			// so if current cluster is not primary, its UpdateReplicateConfiguration will be replicated by CDC,
			// so we should wait until the replication configuration is changed into the same one.
			return &streamingpb.UpdateReplicateConfigurationResponse{}, s.waitUntilPrimaryChangeOrConfigurationSame(ctx, config)
		}
		return nil, err
	}
	defer broadcaster.Close()

	msg, err := s.validateReplicateConfiguration(ctx, config)
	if err != nil {
		if errors.Is(err, errReplicateConfigurationSame) {
			mlog.Info(ctx, "configuration is same after cluster resource key is acquired, ignored")
			return &streamingpb.UpdateReplicateConfigurationResponse{}, nil
		}
		return nil, err
	}
	_, err = broadcaster.Broadcast(ctx, msg)
	if err != nil {
		return nil, err
	}
	return &streamingpb.UpdateReplicateConfigurationResponse{}, nil
}

// waitUntilPrimaryChangeOrConfigurationSame waits until the primary changes or the configuration is same.
func (s *assignmentServiceImpl) waitUntilPrimaryChangeOrConfigurationSame(ctx context.Context, config *commonpb.ReplicateConfiguration) error {
	b, err := balance.GetWithContext(ctx)
	if err != nil {
		return err
	}
	err = b.WatchChannelAssignments(ctx, func(param balancer.WatchChannelAssignmentsCallbackParam) error {
		if proto.Equal(config, param.ReplicateConfiguration) {
			return errAssignmentDone
		}
		return nil
	})
	if errors.Is(err, errAssignmentDone) {
		return nil
	}
	return err
}

// validateReplicateConfiguration validates the replicate configuration.
func (s *assignmentServiceImpl) validateReplicateConfiguration(ctx context.Context, config *commonpb.ReplicateConfiguration) (message.BroadcastMutableMessage, error) {
	balancer, err := balance.GetWithContext(ctx)
	if err != nil {
		return nil, err
	}

	// get all pchannels
	latestAssignment, err := balancer.GetLatestChannelAssignment()
	if err != nil {
		return nil, err
	}

	// double check if the configuration is same after resource key is acquired.
	if proto.Equal(config, latestAssignment.ReplicateConfiguration) {
		return nil, errReplicateConfigurationSame
	}

	cc := channel.GetClusterChannels(channel.OptIncludeUnavailableInReplication())

	// validate the configuration itself
	currentClusterID := paramtable.Get().CommonCfg.ClusterPrefix.GetValue()
	currentConfig := latestAssignment.ReplicateConfiguration
	incomingConfig := config
	validator := replicateutil.NewReplicateConfigValidator(incomingConfig, currentConfig, currentClusterID, cc.Channels)
	if err := validator.Validate(); err != nil {
		mlog.Warn(ctx, "UpdateReplicateConfiguration fail", mlog.Err(err))
		return nil, err
	}

	// TODO: validate the incoming configuration is compatible with the current config.
	if _, err := replicateutil.NewConfigHelper(paramtable.Get().CommonCfg.ClusterPrefix.GetValue(), config); err != nil {
		return nil, err
	}
	b := message.NewAlterReplicateConfigMessageBuilderV2().
		WithHeader(&message.AlterReplicateConfigMessageHeader{
			ReplicateConfiguration: config,
			IsPchannelIncreasing:   validator.IsPChannelIncreasing(),
		}).
		WithBody(&message.AlterReplicateConfigMessageBody{}).
		WithClusterLevelBroadcast(cc).
		MustBuildBroadcast()
	return b, nil
}

// validateForcePromoteConfiguration validates that the force promote configuration is safe.
// Requirements:
// 1. Must contain ONLY the current cluster
// 2. Must have NO topology (no replication relationships)
func validateForcePromoteConfiguration(config *commonpb.ReplicateConfiguration, currentClusterID string) error {
	// Use config helper to validate the configuration structure
	helper, err := replicateutil.NewConfigHelper(currentClusterID, config)
	if err != nil {
		return status.NewInvalidArgument("invalid replicate configuration for force promote: %v", err)
	}

	// Check that configuration contains exactly one cluster (the current cluster)
	if len(config.Clusters) != 1 {
		return status.NewInvalidArgument(
			"force promote requires configuration with exactly one cluster (current cluster only), got %d clusters",
			len(config.Clusters))
	}

	// Check that the single cluster is the current cluster
	if config.Clusters[0].ClusterId != currentClusterID {
		return status.NewInvalidArgument(
			"force promote requires configuration with only current cluster %s, got cluster %s",
			currentClusterID,
			config.Clusters[0].ClusterId)
	}

	// Check that there is NO topology (no replication)
	if len(config.CrossClusterTopology) > 0 {
		return status.NewInvalidArgument(
			"force promote requires configuration with no topology (single primary cluster), got %d topology edges",
			len(config.CrossClusterTopology))
	}

	// Verify the cluster role is primary (should be true for single cluster with no topology)
	if helper.GetCurrentCluster().Role() != replicateutil.RolePrimary {
		return status.NewInvalidArgument("force promote configuration must result in current cluster being primary")
	}

	return nil
}

// handleForcePromote handles force promote logic for replicate configuration.
// It promotes a secondary cluster to standalone primary immediately without waiting for CDC replication.
func (s *assignmentServiceImpl) handleForcePromote(ctx context.Context, config *commonpb.ReplicateConfiguration) (*streamingpb.UpdateReplicateConfigurationResponse, error) {
	mlog.Warn(ctx, "Force promote replicate configuration requested")

	// Use WithSecondaryClusterResourceKey to:
	// 1. Acquire exclusive cluster-level resource key
	// 2. Verify the cluster is secondary (not primary)
	broadcaster, err := broadcast.StartBroadcastWithSecondaryClusterResourceKey(ctx)
	if err != nil {
		if errors.Is(err, broadcast.ErrNotSecondary) {
			return nil, status.NewInvalidArgument("force promote can only be used on secondary clusters, current cluster is primary")
		}
		return nil, err
	}
	defer broadcaster.Close()

	// Validate the caller-supplied config.
	currentClusterID := paramtable.Get().CommonCfg.ClusterPrefix.GetValue()
	if err := validateForcePromoteConfiguration(config, currentClusterID); err != nil {
		return nil, err
	}

	// Derive and construct the actual force-promote config from current etcd state.
	forcePromoteConfig, pchannels, err := s.buildForcePromoteConfiguration(ctx)
	if err != nil {
		return nil, err
	}
	// Config is same (already standalone primary), no-op
	if forcePromoteConfig == nil {
		return &streamingpb.UpdateReplicateConfigurationResponse{}, nil
	}

	// Create the AlterReplicateConfigMessage with force promote flag
	controlChannel := streaming.WAL().ControlChannel()
	broadcastPChannels := lo.Map(pchannels, func(pchannel string, _ int) string {
		if funcutil.IsOnPhysicalChannel(controlChannel, pchannel) {
			return controlChannel
		}
		return pchannel
	})

	msg := message.NewAlterReplicateConfigMessageBuilderV2().
		WithHeader(&message.AlterReplicateConfigMessageHeader{
			ReplicateConfiguration: forcePromoteConfig,
			ForcePromote:           true, // marks as force promote
		}).
		WithBody(&message.AlterReplicateConfigMessageBody{}).
		WithBroadcast(broadcastPChannels, message.OptBuildBroadcastAckSyncUp()). // Disable fast DDL ack
		MustBuildBroadcast()

	// Use Broadcast() to broadcast the message
	// The ACK callback will handle DDL fixing and meta saving
	_, err = broadcaster.Broadcast(ctx, msg)
	if err != nil {
		mlog.Error(ctx, "Failed to broadcast force promote AlterReplicateConfigMessage", mlog.Err(err))
		return nil, err
	}

	mlog.Info(ctx, "Force promote replicate configuration broadcast completed successfully")
	return &streamingpb.UpdateReplicateConfigurationResponse{}, nil
}

// buildForcePromoteConfiguration reads the current cluster state from etcd and constructs
// the force promote configuration. It returns the new config and the list of pchannels.
func (s *assignmentServiceImpl) buildForcePromoteConfiguration(ctx context.Context) (*commonpb.ReplicateConfiguration, []string, error) {
	balancer, err := balance.GetWithContext(ctx)
	if err != nil {
		return nil, nil, err
	}

	latestAssignment, err := balancer.GetLatestChannelAssignment()
	if err != nil {
		return nil, nil, err
	}

	currentClusterID := paramtable.Get().CommonCfg.ClusterPrefix.GetValue()
	currentConfig := latestAssignment.ReplicateConfiguration

	// Force promote requires current config to exist (secondary must have been configured)
	if currentConfig == nil {
		return nil, nil, status.NewInvalidArgument("force promote requires existing replicate configuration; current cluster has no configuration")
	}

	// Get the current cluster from existing config directly (don't construct a new one)
	var currentCluster *commonpb.MilvusCluster
	for _, cluster := range currentConfig.GetClusters() {
		if cluster.GetClusterId() == currentClusterID {
			currentCluster = cluster
			break
		}
	}
	if currentCluster == nil {
		return nil, nil, status.NewInvalidArgument("force promote requires current cluster in existing configuration; cluster %s not found in config", currentClusterID)
	}

	// Get pchannels from PChannelView for validation
	pchannels := lo.MapToSlice(latestAssignment.PChannelView.Channels, func(_ channel.ChannelID, ch *channel.PChannelMeta) string {
		return ch.Name()
	})
	// Sort pchannels for consistent ordering (map iteration order is randomized)
	sort.Strings(pchannels)

	// Construct the standalone primary configuration using the current cluster from existing config
	// This configuration makes the current cluster a standalone primary with no replication
	forcePromoteConfig := &commonpb.ReplicateConfiguration{
		Clusters:             []*commonpb.MilvusCluster{currentCluster},
		CrossClusterTopology: nil, // No topology means standalone primary
	}

	// Double check if configuration is same (already standalone primary)
	if proto.Equal(forcePromoteConfig, currentConfig) {
		mlog.Info(ctx, "configuration is same in force promote, ignored")
		return nil, nil, nil
	}

	// Validate the configuration using existing validator
	validator := replicateutil.NewReplicateConfigValidator(forcePromoteConfig, currentConfig, currentClusterID, pchannels)
	if err := validator.Validate(); err != nil {
		mlog.Warn(ctx, "Force promote replicate configuration validation failed", mlog.Err(err))
		return nil, nil, err
	}

	return forcePromoteConfig, pchannels, nil
}

// alterReplicateConfiguration puts the replicate configuration into the balancer.
// It's a callback function of the broadcast service.
func (s *assignmentServiceImpl) alterReplicateConfiguration(ctx context.Context, result message.BroadcastResultAlterReplicateConfigMessageV2) error {
	header := result.Message.Header()

	// Check ignore field first - skip all processing if true
	// This is used for incomplete switchover messages that should be ignored after force promote
	if header.Ignore {
		mlog.Info(ctx, "AlterReplicateConfig message has ignore flag set, skipping processing",
			mlog.Bool("forcePromote", header.ForcePromote))
		return nil
	}

	balancer, err := balance.GetWithContext(ctx)
	if err != nil {
		return err
	}

	// Update the configuration
	// For force promote, incomplete broadcasts are already fixed by ackCallbackScheduler
	// before this callback is invoked.

	return balancer.UpdateReplicateConfiguration(ctx, result)
}

// UpdateWALBalancePolicy is used to update the WAL balance policy.
func (s *assignmentServiceImpl) UpdateWALBalancePolicy(ctx context.Context, req *streamingpb.UpdateWALBalancePolicyRequest) (*streamingpb.UpdateWALBalancePolicyResponse, error) {
	balancer, err := balance.GetWithContext(ctx)
	if err != nil {
		return nil, err
	}

	return balancer.UpdateBalancePolicy(ctx, req)
}