sdk

README

Sentinel Import SDK

This repository contains the Sentinel import SDK. This SDK allows developers to extend Sentinel to source external information for use in their policies.

Sentinel imports can be written in any language, but the recommended language is Go. We provide a high-level framework to make writing imports in Go extremely easy. For other languages, imports can be written by implementing the protocol over gRPC.

To get started writing a Sentinel import, we recommend reading the extending Sentinel guide.

You can also view the import API via GoDoc.

SDK Compatibility Matrix

Sentinel's plugin protocol is, at this time, not backwards compatible. This means that a specific version of the Sentinel runtime is always coupled to a specific version of the plugin protocol, and SDK. The following table can help you determine which version of the SDK is necessary to work with which versions of Sentinel.

Sentinel Version	Plugin Protocol Version	SDK Version
Current (Up to v0.10.4)	1	Up to v0.1.1
Planned for v0.11.0	2	Since v0.2.0

Development Info

The following tools are required to work with the Sentinel SDK:

• The Sentinel runtime, usually at the most recent version. There are rare exceptions to this, such as when the protocol is in active development. Refer to the SDK Compatibility Matrix to locate the correct version of the SDK to work with the most current version of the runtime.
• Google's Protocol Buffers.

After both of these are installed, you can use the following make commands:

• make test will run tests on the SDK. You can use the TEST and TESTARGS variables to control the packages and test arguments, respectively.
• make tools will install any necessary Go tools.
• make generate will generate any auto-generated code. Currently this includes the protocol, mockery files, and the code for the plugin testing toolkit.

The modules, test-circle, and /usr/bin/sentinel targets are only used in Circle and are not necessary for interactive development.

Help and Discussion

For issues specific to the SDK, please use the GitHub issue tracker (the Issues tab).

For general Sentinel support and discussion, please use the Sentinel Community Forum.

Documentation

Overview

Do not edit mock_Import_Closer.go directly as your changes will be overwritten. Instead, edit mock_Import_Closer.go.src and re-run "go generate ./" in the root SDK package.

Package sdk contains the low-level interfaces and API for creating Sentinel plugins. A Sentinel plugin can provide data dynamically to Sentinel policies.

For plugin authors, the subfolder "framework" contains a high-level framework for easily implementing imports in Go.

Index

• Variables
• type GetKey
  • func (g *GetKey) Call() bool
• type GetReq
  • func (g *GetReq) GetKeys() []string
• type GetResult
• type GetResultList
  • func (r GetResultList) KeyId(id uint64) *GetResult
• type Import
• type MockImport
  • func (_m *MockImport) Configure(_a0 map[string]interface{}) error
  • func (_m *MockImport) Get(reqs []*GetReq) ([]*GetResult, error)
• type MockImportCloser
  • func (_m *MockImportCloser) Close() error

Variables

var (
	// Undefined is a constant value that represents the undefined object in
	// Sentinel. By making this the return value, it'll be converted to
	// Undefined.
	Undefined = &undefined{}

	// Null is a constant value that represents the null object in Sentinel.
	// By making this a return value, it will convert to null.
	Null = &null{}
)

Types

type GetKey

type GetKey struct {
	// The key for this part of the request.
	Key string

	// The list of arguments for a call expression. This is "nil" if
	// this key is not a call. This may be length zero (but non-nil) if
	// this is a call with no arguments.
	Args []interface{}
}

GetKey is an individual key in the larger possible selector of the specific import call, along with any supplied arguments for the specific key.

func (*GetKey) Call

func (g *GetKey) Call() bool

Call returns true if this request is a call expression.

type GetReq

type GetReq struct {
	// ExecId is a unique ID representing the particular execution for this
	// request. This can be used to maintain state locally.
	//
	// ExecDeadline is a hint of when the execution will be over and the
	// state can be thrown away. The time given here will always be in UTC
	// time. Note that this is susceptible to clock shifts, but Go is planning
	// to make the time APIs monotonic by default (see proposal 12914). After
	// that this will be resolved.
	ExecId       uint64
	ExecDeadline time.Time

	// Keys is the list of keys being requested. For example for "a.b.c"
	// where "a" is the import, Keys would be ["b", "c"].
	Keys []GetKey

	// KeyId is a unique ID for this key. This should match exactly the
	// GetResult KeyId so that the result for this can be found quickly.
	KeyId uint64

	// Context, if supplied, is an arbitrary object intended to
	// represent the data from an existing namespace. If the import
	// supports the framework.New interface, the contents are passed to
	// it, with any resulting namespace being what Get operates on.
	//
	// The Get call operates on the root of the import if this is set
	// to nil. If this is set and the import does not implement
	// framework.New, an error is returned.
	Context map[string]interface{}
}

GetReq are the arguments given to Get for an Import.

func (*GetReq) GetKeys

func (g *GetReq) GetKeys() []string

GetKeys returns a list of the string keys in the GetReq, without the arguments.

type GetResult

type GetResult struct {
	KeyId    uint64                 // KeyId matching GetReq.KeyId, or zero.
	Keys     []string               // Keys structure from GetReq.Keys, or new key set.
	Value    interface{}            // Value compatible with lang/object.ToObject
	Context  map[string]interface{} // Updated Context if it was sent
	Callable bool                   // true if returned Value is callable
}

GetResult is the result structure for a Get request.

type GetResultList

type GetResultList []*GetResult

GetResultList is a wrapper around a slice of GetResult structures to provide helpers.

func (GetResultList) KeyId

func (r GetResultList) KeyId(id uint64) *GetResult

KeyId gets the result with the given key ID, or nil if its not found.

type Import

type Import interface {
	// Configure is called to configure the plugin before it is accessed.
	// This must be called before any call to Get().
	Configure(map[string]interface{}) error

	// Get is called when an import field is accessed or called as a function.
	//
	// Get may request more than one value at a time, represented by multiple
	// GetReq values. The result GetResult should contain the matching
	// KeyId for the requests.
	//
	// The result value is not a map keyed on KeyId to allow flexibility
	// in the future of potentially allowing pre-fetched data. This has no
	// effect currently.
	Get(reqs []*GetReq) ([]*GetResult, error)
}

Import is an importable package.

Imports are a namespace that may contain objects and functions. The root level has no value nor can it be called. For example `import "a'` allows access to fields within "a" such as `a.b` but doesn't allow referencing or calling it directly with `a` alone. This is an important difference between imports and external objects (which themselves express a value).

type MockImport

type MockImport struct {
	mock.Mock
}

MockImport is an autogenerated mock type for the Import type

func (*MockImport) Configure

func (_m *MockImport) Configure(_a0 map[string]interface{}) error

Configure provides a mock function with given fields: _a0

func (*MockImport) Get

func (_m *MockImport) Get(reqs []*GetReq) ([]*GetResult, error)

Get provides a mock function with given fields: reqs

type MockImportCloser

type MockImportCloser struct {
	MockImport
}

MockImportCloser augments MockImport to also implement io.Closer

func (*MockImportCloser) Close

func (_m *MockImportCloser) Close() error

Close mocks Close for MockImportCloser