google.golang.org/grpc@v1.62.1/xds/internal/xdsclient/xdsresource/type.go (about)

     1  /*
     2   *
     3   * Copyright 2021 gRPC authors.
     4   *
     5   * Licensed under the Apache License, Version 2.0 (the "License");
     6   * you may not use this file except in compliance with the License.
     7   * You may obtain a copy of the License at
     8   *
     9   *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  
    18  package xdsresource
    19  
    20  import (
    21  	"time"
    22  
    23  	v3discoverypb "github.com/envoyproxy/go-control-plane/envoy/service/discovery/v3"
    24  	"google.golang.org/grpc/xds/internal/xdsclient/xdsresource/version"
    25  	"google.golang.org/protobuf/proto"
    26  	"google.golang.org/protobuf/types/known/anypb"
    27  )
    28  
    29  // UpdateValidatorFunc performs validations on update structs using
    30  // context/logic available at the xdsClient layer. Since these validation are
    31  // performed on internal update structs, they can be shared between different
    32  // API clients.
    33  type UpdateValidatorFunc func(any) error
    34  
    35  // UpdateMetadata contains the metadata for each update, including timestamp,
    36  // raw message, and so on.
    37  type UpdateMetadata struct {
    38  	// Status is the status of this resource, e.g. ACKed, NACKed, or
    39  	// Not_exist(removed).
    40  	Status ServiceStatus
    41  	// Version is the version of the xds response. Note that this is the version
    42  	// of the resource in use (previous ACKed). If a response is NACKed, the
    43  	// NACKed version is in ErrState.
    44  	Version string
    45  	// Timestamp is when the response is received.
    46  	Timestamp time.Time
    47  	// ErrState is set when the update is NACKed.
    48  	ErrState *UpdateErrorMetadata
    49  }
    50  
    51  // IsListenerResource returns true if the provider URL corresponds to an xDS
    52  // Listener resource.
    53  func IsListenerResource(url string) bool {
    54  	return url == version.V3ListenerURL
    55  }
    56  
    57  // IsHTTPConnManagerResource returns true if the provider URL corresponds to an xDS
    58  // HTTPConnManager resource.
    59  func IsHTTPConnManagerResource(url string) bool {
    60  	return url == version.V3HTTPConnManagerURL
    61  }
    62  
    63  // IsRouteConfigResource returns true if the provider URL corresponds to an xDS
    64  // RouteConfig resource.
    65  func IsRouteConfigResource(url string) bool {
    66  	return url == version.V3RouteConfigURL
    67  }
    68  
    69  // IsClusterResource returns true if the provider URL corresponds to an xDS
    70  // Cluster resource.
    71  func IsClusterResource(url string) bool {
    72  	return url == version.V3ClusterURL
    73  }
    74  
    75  // IsEndpointsResource returns true if the provider URL corresponds to an xDS
    76  // Endpoints resource.
    77  func IsEndpointsResource(url string) bool {
    78  	return url == version.V3EndpointsURL
    79  }
    80  
    81  // UnwrapResource unwraps and returns the inner resource if it's in a resource
    82  // wrapper. The original resource is returned if it's not wrapped.
    83  func UnwrapResource(r *anypb.Any) (*anypb.Any, error) {
    84  	url := r.GetTypeUrl()
    85  	if url != version.V3ResourceWrapperURL {
    86  		// Not wrapped.
    87  		return r, nil
    88  	}
    89  	inner := &v3discoverypb.Resource{}
    90  	if err := proto.Unmarshal(r.GetValue(), inner); err != nil {
    91  		return nil, err
    92  	}
    93  	return inner.Resource, nil
    94  }
    95  
    96  // ServiceStatus is the status of the update.
    97  type ServiceStatus int
    98  
    99  const (
   100  	// ServiceStatusUnknown is the default state, before a watch is started for
   101  	// the resource.
   102  	ServiceStatusUnknown ServiceStatus = iota
   103  	// ServiceStatusRequested is when the watch is started, but before and
   104  	// response is received.
   105  	ServiceStatusRequested
   106  	// ServiceStatusNotExist is when the resource doesn't exist in
   107  	// state-of-the-world responses (e.g. LDS and CDS), which means the resource
   108  	// is removed by the management server.
   109  	ServiceStatusNotExist // Resource is removed in the server, in LDS/CDS.
   110  	// ServiceStatusACKed is when the resource is ACKed.
   111  	ServiceStatusACKed
   112  	// ServiceStatusNACKed is when the resource is NACKed.
   113  	ServiceStatusNACKed
   114  )
   115  
   116  // UpdateErrorMetadata is part of UpdateMetadata. It contains the error state
   117  // when a response is NACKed.
   118  type UpdateErrorMetadata struct {
   119  	// Version is the version of the NACKed response.
   120  	Version string
   121  	// Err contains why the response was NACKed.
   122  	Err error
   123  	// Timestamp is when the NACKed response was received.
   124  	Timestamp time.Time
   125  }
   126  
   127  // UpdateWithMD contains the raw message of the update and the metadata,
   128  // including version, raw message, timestamp.
   129  //
   130  // This is to be used for config dump and CSDS, not directly by users (like
   131  // resolvers/balancers).
   132  type UpdateWithMD struct {
   133  	MD  UpdateMetadata
   134  	Raw *anypb.Any
   135  }