Documentation
¶
Overview ¶
Example (Read) ¶
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"github.com/IUAD1IY7/opa/v1/storage"
"github.com/IUAD1IY7/opa/v1/storage/inmem"
)
func main() {
// Initialize context for the example. Normally the caller would obtain the
// context from an input parameter or instantiate their own.
ctx := context.Background()
// Define some dummy data to initialize the built-in store with.
exampleInput := `
{
"users": [
{
"name": "alice",
"color": "red",
"likes": ["clouds", "ships"]
},
{
"name": "burt",
"likes": ["cheese", "wine"]
}
]
}
`
var data map[string]any
// OPA uses Go's standard JSON library but assumes that numbers have been
// decoded as json.Number instead of float64. You MUST decode with UseNumber
// enabled.
decoder := json.NewDecoder(bytes.NewBufferString(exampleInput))
decoder.UseNumber()
if err := decoder.Decode(&data); err != nil {
// Handle error.
}
// Instantiate the storage layer.
store := inmem.NewFromObject(data)
txn, err := store.NewTransaction(ctx)
if err != nil {
// Handle error.
}
// Cancel transaction because no writes are performed.
defer store.Abort(ctx, txn)
// Read values out of storage.
v1, err1 := store.Read(ctx, txn, storage.MustParsePath("/users/1/likes/1"))
v2, err2 := store.Read(ctx, txn, storage.MustParsePath("/users/0/age"))
// Inspect the return values.
fmt.Println("v1:", v1)
fmt.Println("err1:", err1)
fmt.Println("v2:", v2)
fmt.Println("err2:", err2)
fmt.Println("err2 is not found:", storage.IsNotFound(err2))
}
Output: v1: wine err1: <nil> v2: <nil> err2: storage_not_found_error: /users/0/age: document does not exist err2 is not found: true
Example (Write) ¶
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"github.com/IUAD1IY7/opa/v1/storage"
"github.com/IUAD1IY7/opa/v1/storage/inmem"
)
func main() {
// Initialize context for the example. Normally the caller would obtain the
// context from an input parameter or instantiate their own.
ctx := context.Background()
// Define some dummy data to initialize the DataStore with.
exampleInput := `
{
"users": [
{
"name": "alice",
"color": "red",
"likes": ["clouds", "ships"]
},
{
"name": "burt",
"likes": ["cheese", "wine"]
}
]
}
`
var data map[string]any
// OPA uses Go's standard JSON library but assumes that numbers have been
// decoded as json.Number instead of float64. You MUST decode with UseNumber
// enabled.
decoder := json.NewDecoder(bytes.NewBufferString(exampleInput))
decoder.UseNumber()
if err := decoder.Decode(&data); err != nil {
// Handle error.
}
// Create the new store with the dummy data.
store := inmem.NewFromObject(data)
// Define dummy data to add to the DataStore.
examplePatch := `{
"longitude": 82.501389,
"latitude": -62.338889
}`
var patch any
// See comment above regarding decoder usage.
decoder = json.NewDecoder(bytes.NewBufferString(examplePatch))
decoder.UseNumber()
if err := decoder.Decode(&patch); err != nil {
// Handle error.
}
txn, err := store.NewTransaction(ctx, storage.WriteParams)
if err != nil {
// Handle error.
}
// Write values into storage and read result.
err0 := store.Write(ctx, txn, storage.AddOp, storage.MustParsePath("/users/0/location"), patch)
v1, err1 := store.Read(ctx, txn, storage.MustParsePath("/users/0/location/latitude"))
err2 := store.Write(ctx, txn, storage.ReplaceOp, storage.MustParsePath("/users/1/color"), "red")
// Inspect the return values.
fmt.Println("err0:", err0)
fmt.Println("v1:", v1)
fmt.Println("err1:", err1)
fmt.Println("err2:", err2)
// Rollback transaction because write failed.
store.Abort(ctx, txn)
}
Output: err0: <nil> v1: -62.338889 err1: <nil> err2: storage_not_found_error: /users/1/color: document does not exist
Index ¶
- Constants
- func DeepCopy(val any) any
- func InterfaceMaps(a map[string]any, b map[string]any) (map[string]any, bool)
- func Map(val map[string]any) map[string]any
- func New() storage.Store
- func NewFromObject(data map[string]any) storage.Store
- func NewFromObjectWithOpts(data map[string]any, opts ...Opt) storage.Store
- func NewFromReader(r io.Reader) storage.Store
- func NewFromReaderWithOpts(r io.Reader, opts ...Opt) storage.Store
- func NewNotFoundError(path storage.Path) *storage.Error
- func NewNotFoundErrorWithHint(path storage.Path, hint string) *storage.Error
- func NewNotFoundErrorf(f string, a ...any) *storage.Error
- func NewWithOpts(opts ...Opt) storage.Store
- func NewWriteConflictError(p storage.Path) *storage.Error
- func Ptr(data any, path storage.Path) (any, error)
- func ValidateASTArrayIndex(arr *ast.Array, s string, path storage.Path) (int, error)
- func ValidateArrayIndex(arr []any, s string, path storage.Path) (int, error)
- func ValidateArrayIndexForWrite(arr []any, s string, i int, path storage.Path) (int, error)
- func ValuePtr(data ast.Value, path storage.Path) (ast.Value, error)
- type Opt
Examples ¶
Constants ¶
const ArrayIndexTypeMsg = "array index must be integer"
const DoesNotExistMsg = "document does not exist"
const OutOfRangeMsg = "array index out of range"
Variables ¶
This section is empty.
Functions ¶
func InterfaceMaps ¶
InterfaceMaps returns the result of merging a and b. If a and b cannot be merged because of conflicting key-value pairs, ok is false.
func NewFromObject ¶
NewFromObject returns a new in-memory store from the supplied data object.
func NewFromObjectWithOpts ¶
NewFromObjectWithOpts returns a new in-memory store from the supplied data object, with the options passed.
func NewFromReader ¶
NewFromReader returns a new in-memory store from a reader that produces a JSON serialized object. This function is for test purposes.
func NewFromReaderWithOpts ¶
NewFromReader returns a new in-memory store from a reader that produces a JSON serialized object, with extra options. This function is for test purposes.
func NewWithOpts ¶
NewWithOpts returns an empty in-memory store, with extra options passed.
func ValidateASTArrayIndex ¶
func ValidateArrayIndex ¶
func ValidateArrayIndexForWrite ¶
ValidateArrayIndexForWrite also checks that `s` is a valid way to address an array element like `ValidateArrayIndex`, but returns a `resource_conflict` error if it is not.
Types ¶
type Opt ¶
type Opt func(*store)
An Opt modifies store at instantiation.
func OptReturnASTValuesOnRead ¶
OptReturnASTValuesOnRead sets whether data values added to the store should be eagerly converted to AST values, which are then returned on read.
When enabled, this feature does not sanity check data before converting it to AST values, which may result in panics if the data is not valid. Callers should ensure that passed data can be serialized to AST values; otherwise, it's recommended to also enable OptRoundTripOnWrite.
func OptRoundTripOnWrite ¶
OptRoundTripOnWrite sets whether incoming objects written to store are round-tripped through JSON to ensure they are serializable to JSON.
Callers should disable this if they can guarantee all objects passed to Write() are serializable to JSON. Failing to do so may result in undefined behavior, including panics.
Usually, when only storing objects in the inmem store that have been read via encoding/json, this is safe to disable, and comes with an improvement in performance and memory use.
If setting to false, callers should deep-copy any objects passed to Write() unless they can guarantee the objects will not be mutated after being written, and that mutations happening to the objects after they have been passed into Write() don't affect their logic.