/*
Copyright 2017 The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package statefulset

import (
	"context"
	"fmt"

	apps "k8s.io/api/apps/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
	clientset "k8s.io/client-go/kubernetes"
	appslisters "k8s.io/client-go/listers/apps/v1"
	"k8s.io/client-go/util/retry"
)

// StatefulSetStatusUpdaterInterface is an interface used to update the StatefulSetStatus associated with a StatefulSet.
// For any use other than testing, clients should create an instance using NewRealStatefulSetStatusUpdater.
type StatefulSetStatusUpdaterInterface interface {
	// UpdateStatefulSetStatus sets the set's Status to status. Implementations are required to retry on conflicts,
	// but fail on other errors. If the returned error is nil set's Status has been successfully set to status.
	UpdateStatefulSetStatus(ctx context.Context, set *apps.StatefulSet, status *apps.StatefulSetStatus) error
}

//这段代码定义了一个名为StatefulSetStatusUpdaterInterface的接口，其中包含一个方法UpdateStatefulSetStatus。
//该方法用于更新与StatefulSet关联的StatefulSetStatus。
//接口的实现需要在发生冲突时进行重试，但在其他错误情况下失败。
//如果返回的错误为nil，则表示set的状态已成功设置为status。

// NewRealStatefulSetStatusUpdater returns a StatefulSetStatusUpdaterInterface that updates the Status of a StatefulSet,
// using the supplied client and setLister.
func NewRealStatefulSetStatusUpdater(
	client clientset.Interface,
	setLister appslisters.StatefulSetLister) StatefulSetStatusUpdaterInterface {
	return &realStatefulSetStatusUpdater{client, setLister}
}

//该函数返回一个StatefulSetStatusUpdaterInterface接口，
//用于更新StatefulSet的状态。
//它接受一个clientset.Interface类型的client和一个appslisters.StatefulSetLister类型的setLister作为参数，
//并将它们封装到realStatefulSetStatusUpdater结构体中，然后返回该结构体的指针。

type realStatefulSetStatusUpdater struct {
	client    clientset.Interface
	setLister appslisters.StatefulSetLister
}

func (ssu *realStatefulSetStatusUpdater) UpdateStatefulSetStatus(
	ctx context.Context,
	set *apps.StatefulSet,
	status *apps.StatefulSetStatus) error {
	// don't wait due to limited number of clients, but backoff after the default number of steps
	return retry.RetryOnConflict(retry.DefaultRetry, func() error {
		set.Status = *status
		// TODO: This context.TODO should use a real context once we have RetryOnConflictWithContext
		_, updateErr := ssu.client.AppsV1().StatefulSets(set.Namespace).UpdateStatus(context.TODO(), set, metav1.UpdateOptions{})
		if updateErr == nil {
			return nil
		}
		if updated, err := ssu.setLister.StatefulSets(set.Namespace).Get(set.Name); err == nil {
			// make a copy so we don't mutate the shared cache
			set = updated.DeepCopy()
		} else {
			utilruntime.HandleError(fmt.Errorf("error getting updated StatefulSet %s/%s from lister: %v", set.Namespace, set.Name, err))
		}

		return updateErr
	})
}

//这段Go代码定义了一个realStatefulSetStatusUpdater结构体和一个UpdateStatefulSetStatus方法。
//realStatefulSetStatusUpdater结构体包含两个字段：client和setLister，分别用于与Kubernetes API通信和获取StatefulSet列表。
//UpdateStatefulSetStatus方法用于更新指定StatefulSet的状态。它使用retry.RetryOnConflict函数进行重试，
//以处理并发更新冲突的情况。在重试的回调函数中，将新状态赋值给set.Status，
//然后调用UpdateStatus方法更新StatefulSet的状态。
//如果更新失败，将尝试从setLister获取最新的StatefulSet副本，并再次尝试更新。
//如果获取最新StatefulSet时出现错误，将记录错误信息。
//总结来说，这个函数的作用是更新指定StatefulSet的状态，处理并发更新冲突，并在更新失败时进行重试。

var _ StatefulSetStatusUpdaterInterface = &realStatefulSetStatusUpdater{}