framework

README

SGNL ingestion adapter framework

Documentation

Index

• func AddAttribute[Value AttributeValue](object Object, attributeExternalId string, value Value) error
• func AddChildObjects(object Object, entityExternalId string, childObjects ...Object) error
• type Adapter
• type AttributeConfig
• type AttributeType
• type AttributeValue
• type BasicAuthCredentials
• type DatasourceAuthCredentials
• type Duration
  • func ParseISO8601Duration(durationStr string) (*Duration, error)
• type EntityConfig
• type Error
• type Object
• type Page
• type Request
• type Response
  • func NewGetPageResponseError(err *Error) Response
  • func NewGetPageResponseSuccess(page *Page) Response

Functions

func AddAttribute

func AddAttribute[Value AttributeValue](object Object, attributeExternalId string, value Value) error

AddAttribute adds a attribute into the given object. Returns an error if an attribute or child object has already been added with the same external ID.

func AddChildObjects

func AddChildObjects(object Object, entityExternalId string, childObjects ...Object) error

AddChildObjects adds child objects into the given object. If child objects have already been added for the same entity external ID, the given objects are appended to the list of child objects in that entity. Returns an error if an attribute has already been added with the same external ID.

Types

type Adapter

type Adapter[Config any] interface {
	// GetPage returns a page of objects from the requested datasource for the
	// requested entity.
	GetPage(ctx context.Context, request *Request[Config]) Response
}

Adapter is the high-level interface implemented by adapters.

The Config type parameter must be a struct type the configuration JSON object can be unmarshaled into.

type AttributeConfig

type AttributeConfig struct {
	// ExternalId is the adapter-specific name of the attribute in the entity.
	ExternalId string `json:"externalId"`

	// Type is the type of the attribute's values.
	Type AttributeType `json:"type"`

	// List indicates whether the attribute contains a list of values vs. a
	// single value.
	List bool `json:"list,omitempty"`

	// Indicates whether the attribute represents a unique identifier for the entity.
	UniqueId bool `json:"unique_id,omitempty"`
}

AttributeConfig is the configuration of an attribute to return.

type AttributeType

type AttributeType int32

AttributeType is the type of the values for an attribute.

const (
	// Boolean.
	AttributeTypeBool AttributeType = 1
	// Date or timestamp.
	AttributeTypeDateTime AttributeType = 2
	// Double-precision float.
	AttributeTypeDouble AttributeType = 3
	// Duration.
	AttributeTypeDuration AttributeType = 4
	// Signed integer.
	AttributeTypeInt64 AttributeType = 5
	// String.
	AttributeTypeString AttributeType = 6
)

type AttributeValue

type AttributeValue interface {
	// Types of non-list attribute values.
	bool | time.Time | Duration | float64 | int64 | string |

		[]bool | []time.Time | []Duration | []float64 | []int64 | []string
}

AttributeValue is the set of types allowed for values of non-list attributes in an Object.

type BasicAuthCredentials

type BasicAuthCredentials struct {
	Username string `json:"username,omitempty"`
	Password string `json:"password,omitempty"`
}

BasicAuthCredentials contains credentials for basic username/password authentication with a datasource.

type DatasourceAuthCredentials

type DatasourceAuthCredentials struct {
	// Basic contains the credentials for basic username/password
	// authentication.
	Basic *BasicAuthCredentials `json:"basic,omitempty"`

	// HTTPAuthorization contains the credentials to be sent in an HTTP Authorization header.
	// Prefixed with the scheme, e.g. "Bearer ".
	HTTPAuthorization string `json:"httpAuthorization,omitempty"`
}

DatasourceAuthCredentials contains the credentials to authenticate with a datasource. Exactly one field is non-nil.

type Duration

type Duration struct {
	// Nanos is a duration as a number of nanoseconds.
	Nanos int32 `json:"nanos,omitempty"`

	// Seconds is a duration as a number of seconds.
	Seconds int64 `json:"seconds,omitempty"`

	// Days is a duration as a number of days.
	Days int64 `json:"days,omitempty"`

	// Months is a duration as a number of months.
	Months int64 `json:"months,omitempty"`
}

Duration is the value of an attribute of type duration. It is the sum of all the fields' durations.

func ParseISO8601Duration

func ParseISO8601Duration(durationStr string) (*Duration, error)

ParseDuration parses a valid ISO8601 duration string into a Duration. Years as duration is not supported. Fractional components of durations are not supported.

type EntityConfig

type EntityConfig struct {
	// Id is the internal identifier of the entity within the datasource.
	// This is generated by SGNL.
	Id string `json:"id"`

	// ExternalId is the external identifier of the entity within the datasource.
	ExternalId string `json:"externalId"`

	// Attributes is the configuration of the attributes to return for the
	// entity.
	// Contains at least the entity's unique ID attribute.
	Attributes []*AttributeConfig `json:"attributes"`

	// ChildEntities is the configuration of the entities that are children of
	// the entity to return together with the entity.
	// Optional.
	ChildEntities []*EntityConfig `json:"childEntities,omitempty"`
}

EntityConfig is the configuration of an entity to get data from.

type Error

type Error struct {
	// Message is the error message.
	// By convention, should start with an upper-case letter and not end with
	// punctuation.
	// Optional.
	Message string `json:"message,omitempty"`

	// Code is the error code indicating the cause of the error.
	Code api_adapter_v1.ErrorCode `json:"code"`

	// RetryAfter is the recommended minimal duration after which this request
	// may be retried.
	// Optional.
	RetryAfter *time.Duration `json:"retryAfter,omitempty"`
}

Error contains the details of an error that occurred while executing a GetPage request.

type Object

type Object map[string]any

Object is an object returned for the top entity or a child entity. Each key is the external ID of an attribute or of a child entity.

Entries should be added into an Object by calling functions AddAttribute and AddChildObjects to ensure that the correct types are used for values.

type Page

type Page struct {
	// Objects is the set of objects in the page returned by the datasource for
	// the requested entity.
	// Optional.
	Objects []Object `json:"objects,omitempty"`

	// NextCursor the cursor that identifies the first object of the next page.
	// Optional. If not set, this page is the last page for this entity.
	NextCursor string `json:"nextCursor,omitempty"`
}

Page contains the objects requested by a GetPage request.

type Request

type Request[Config any] struct {
	// DatasourceID is the ID of the datasource.
	// Required.
	DatasourceID string `json:"datasourceID"`

	// Config is configuration for the datasource.
	// Optional.
	Config *Config `json:"config,omitempty"`

	// Address is the address of the datasource.
	// Optional.
	Address string `json:"address,omitempty"`

	// Auth contains the credentials to use to authenticate with the
	// datasource.
	// Optional.
	Auth *DatasourceAuthCredentials `json:"auth,omitempty"`

	// Entity is the configuration of the entity to get data from.
	Entity EntityConfig `json:"entityConfig"`

	// Ordered indicates whether the entity's objects are ordered by ID, i.e.
	// whether the response must contain objects ordered by monotonically
	// increasing IDs for the entity.
	// If true and the adapter cannot return objects ordered by ID, the adapter
	// must return error code ErrorCode_ERROR_CODE_INVALID_ENTITY_CONFIG.
	Ordered bool `json:"ordered,omitempty"`

	// PageSize is the maximum number of objects to return from the entity.
	PageSize int64 `json:"pageSize"`

	// Cursor identifies the first object of the page to return, as returned by
	// the last call to GetPage for the entity.
	// Optional. If not set, return the first page for this entity.
	Cursor string `json:"cursor,omitempty"`
}

Request is a request for a page of objects from a datasource for an entity.

The Config type parameter must be a struct type the configuration JSON object can be unmarshaled into.

type Response

type Response struct {
	Success *Page  `json:"success,omitempty"`
	Error   *Error `json:"error,omitempty"`
}

Response is the response to a GetPage request. Exactly one field must be non-nil.

func NewGetPageResponseError

func NewGetPageResponseError(err *Error) Response

NewGetPageResponseError returns a Response with the given error.

func NewGetPageResponseSuccess

func NewGetPageResponseSuccess(page *Page) Response

NewGetPageResponseSuccess returns a Response with the given page.