cache.go raw

   1  // Copyright (c) Microsoft Corporation.
   2  // Licensed under the MIT license.
   3  
   4  /*
   5  Package cache allows third parties to implement external storage for caching token data
   6  for distributed systems or multiple local applications access.
   7  
   8  The data stored and extracted will represent the entire cache. Therefore it is recommended
   9  one msal instance per user. This data is considered opaque and there are no guarantees to
  10  implementers on the format being passed.
  11  */
  12  package cache
  13  
  14  import "context"
  15  
  16  // Marshaler marshals data from an internal cache to bytes that can be stored.
  17  type Marshaler interface {
  18  	Marshal() ([]byte, error)
  19  }
  20  
  21  // Unmarshaler unmarshals data from a storage medium into the internal cache, overwriting it.
  22  type Unmarshaler interface {
  23  	Unmarshal([]byte) error
  24  }
  25  
  26  // Serializer can serialize the cache to binary or from binary into the cache.
  27  type Serializer interface {
  28  	Marshaler
  29  	Unmarshaler
  30  }
  31  
  32  // ExportHints are suggestions for storing data.
  33  type ExportHints struct {
  34  	// PartitionKey is a suggested key for partitioning the cache
  35  	PartitionKey string
  36  }
  37  
  38  // ReplaceHints are suggestions for loading data.
  39  type ReplaceHints struct {
  40  	// PartitionKey is a suggested key for partitioning the cache
  41  	PartitionKey string
  42  }
  43  
  44  // ExportReplace exports and replaces in-memory cache data. It doesn't support nil Context or
  45  // define the outcome of passing one. A Context without a timeout must receive a default timeout
  46  // specified by the implementor. Retries must be implemented inside the implementation.
  47  type ExportReplace interface {
  48  	// Replace replaces the cache with what is in external storage. Implementors should honor
  49  	// Context cancellations and return context.Canceled or context.DeadlineExceeded in those cases.
  50  	Replace(ctx context.Context, cache Unmarshaler, hints ReplaceHints) error
  51  	// Export writes the binary representation of the cache (cache.Marshal()) to external storage.
  52  	// This is considered opaque. Context cancellations should be honored as in Replace.
  53  	Export(ctx context.Context, cache Marshaler, hints ExportHints) error
  54  }
  55