1// Copyright (c) Microsoft Corporation.
 2// Licensed under the MIT license.
 3
 4/*
 5Package cache allows third parties to implement external storage for caching token data
 6for distributed systems or multiple local applications access.
 7
 8The data stored and extracted will represent the entire cache. Therefore it is recommended
 9one msal instance per user. This data is considered opaque and there are no guarantees to
10implementers on the format being passed.
11*/
12package cache
13
14import "context"
15
16// Marshaler marshals data from an internal cache to bytes that can be stored.
17type Marshaler interface {
18	Marshal() ([]byte, error)
19}
20
21// Unmarshaler unmarshals data from a storage medium into the internal cache, overwriting it.
22type Unmarshaler interface {
23	Unmarshal([]byte) error
24}
25
26// Serializer can serialize the cache to binary or from binary into the cache.
27type Serializer interface {
28	Marshaler
29	Unmarshaler
30}
31
32// ExportHints are suggestions for storing data.
33type ExportHints struct {
34	// PartitionKey is a suggested key for partitioning the cache
35	PartitionKey string
36}
37
38// ReplaceHints are suggestions for loading data.
39type 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.
47type 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}