agrirouter

README

agrirouter Go SDK

Go SDK for agrirouter is a library that provides a shared interface to access functionality common for agrirouter applications.

🚧🚧🚧 Currently this is ONLY intended to be used internally by agrirouter outbound integrations! 🚧🚧🚧

🚧🚧🚧 External use is NOT SUPPORTED 🚧🚧🚧

Development

Following instructions are for developers working on this SDK.

Prerequisites

• Go 1.23 or later
• bash or compatible shell
• Docker
• make (optional, for convenience)

Install git hooks

Run this command:

git config core.hooksPath .githooks

This will set up git hooks to run minimal set of checks on commit and push. These would not require make.

Code Generation

Script tools/oapi/generate.sh would generate Go code from the OpenAPI specification files.

It uses oapi-codegen tool using dockerized installation, hence it only requires Docker to be installed and bash to run the script that invokes docker.

Cheatsheet

make will run everything: code generation, tidying, full linting and tests.

make test will run tests only.

make vet will run go vet on the library code.

make vet-test-server will run go vet on the test server code.

make vet-all will run go vet on both above.

make lint will run vet for all library and other linters for recently added changes (against the HEAD).

make lint-all will run vet and linters for all files.

make generate will run code generation.

make tidy will run go mod tidy.

make tidy-test-server will run go mod tidy for the test server code.

make tidy-all will run go mod tidy for both library and test server code.

Documentation

Overview

Package agrirouter provides a client for interacting with the new agrirouter API.

Index

• Constants
• Variables
• type Client
  • func NewClient(serverURL string, opts ...ClientOption) (*Client, error)
  • func (c *Client) PutEndpoint(ctx context.Context, externalID string, params *PutEndpointParams, ...) (*Endpoint, error)
  • func (c *Client) ReceiveFiles(ctx context.Context, fileHandler func(ctx context.Context, file *File), ...) error
  • func (c *Client) ReceiveMessages(ctx context.Context, messageHandler MessageHandler, ...) error
  • func (c *Client) SendMessages(ctx context.Context, params *SendMessagesParams, body io.Reader) error
• type ClientOption
  • func WithHTTPClient(httpClient *http.Client) ClientOption
  • func WithPayloadsHTTPClient(httpClient PayloadsHTTPClient) ClientOption
  • func WithRequestEditorFn(fn RequestEditorFn) ClientOption
• type Endpoint
• type EndpointCapability
• type EndpointCapabilityDirection
• type EndpointSubscription
• type EndpointType
• type File
• type Message
• type MessageHandler
• type MessageReceivedEventData
• type PayloadsHTTPClient
• type PutEndpointParams
• type PutEndpointRequest
• type RequestEditorFn
• type SendMessagesParams

Constants

const CapabilityDirectionReceive = internal_models.RECEIVE

CapabilityDirectionReceive indicates capability of endpoint to receive messages.

const CapabilityDirectionSend = internal_models.SEND

CapabilityDirectionSend indicates capability of endpoint to send messages.

const CapabilityDirectionSendReceive = internal_models.SENDRECEIVE

CapabilityDirectionSendReceive indicates capability of endpoint to both send and receive messages.

const CommunicationUnit = internal_models.CommunicationUnit

CommunicationUnit is an endpoint type representing a communication unit.

Communication units are typically devices that can send and receive agrirouter messages, which are installed inside of a vehicle or a machine.

const FarmingSoftware = internal_models.FarmingSoftware

FarmingSoftware is an endpoint type representing farming software applications.

Farming software applications can send and receive agrirouter messages, and they are typically cloud deployed applications that manage agricultural data and provide farmers with their own typically web-based user interface.

const VirtualCommunicationUnit = internal_models.VirtualCommunicationUnit

VirtualCommunicationUnit is an endpoint type representing a virtual communication unit.

Virtual communication units like usual communication units represent devices that can send and receive agrirouter messages, but they are doing so indirectly via their own cloud service, which is not installed inside of a vehicle or a machine.

Variables

var (
	// ErrPutEndpointFailed is returned when an error occurs while trying to put an endpoint.
	ErrPutEndpointFailed = errors.New("failed to put endpoint")

	// ErrFailedStatusCode is returned when the agrirouter API returns a status code that is not expected.
	ErrFailedStatusCode = errors.New("unexpected status code received from agrirouter API")

	// ErrAPICallFailed is returned when an API call fails due to network or server issues.
	ErrAPICallFailed = errors.New("API call failed")

	// ErrURLIsInvalid is returned when the provided URL is invalid.
	ErrURLIsInvalid = errors.New("provided URL is invalid")
)

var ErrFailedToFetchPayload = errors.New("failed to fetch payload")

ErrFailedToFetchPayload is returned when calling agrirouter to fetch message payload fails.

var ErrFailedToReadPayload = errors.New("failed to read payload")

ErrFailedToReadPayload is returned when reading the payload from the response fails.

var ErrMissingPayload = errors.New("missing payload: no embedded payload and no payload URI")

ErrMissingPayload is returned when agrirouter returned no embedded payload with message nor a payload URI.

var ErrToCloseResponseBody = errors.New("failed to close response body")

ErrToCloseResponseBody is returned when closing the response body fails.

var ErrUnexpectedStatusCodeWhenFetchingPayload = errors.New("unexpected status code when fetching payload")

ErrUnexpectedStatusCodeWhenFetchingPayload is returned when the agrirouter API returns an unexpected status code when fetching message payload.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the structure that allows interaction with the agrirouter API.

func NewClient

func NewClient(serverURL string, opts ...ClientOption) (*Client, error)

NewClient creates a new agrirouter client with the given server URL. The server URL should be the base URL of the agrirouter API, e.g. "https://api.qa.agrirouter.farm".

func (*Client) PutEndpoint

func (c *Client) PutEndpoint(
	ctx context.Context,
	externalID string,
	params *PutEndpointParams,
	req *PutEndpointRequest,
) (*Endpoint, error)

PutEndpoint sends a request to the agrirouter API to create or update an endpoint.

Identifier externalId must uniquely identify created or updated endpoint, if endpoint with the same externalId already exists, it will be updated, but only if client is authorized to change that endpoint, f.e application owns it.

The request body must contain all endpoint capabilities and subscriptions. It is not possible to update only part of endpoint configuration. For example if subscriptions are not provided, they will be removed (set to empty list).

func (*Client) ReceiveFiles

func (c *Client) ReceiveFiles(
	ctx context.Context,
	fileHandler func(
		ctx context.Context,
		file *File,
	),
	errorHandler func(err error),
) error

ReceiveFiles listens for incoming files from the agrirouter API and calls the provided handler for each received file.

This function blocks until the context is canceled or an error occurs. It is recommended to run this function in a separate goroutine.

func (*Client) ReceiveMessages

func (c *Client) ReceiveMessages(
	ctx context.Context,
	messageHandler MessageHandler,
	errorHandler func(err error),
) error

ReceiveMessages listens for incoming messages from the agrirouter API and calls the provided handler for each received message.

This function blocks until the context is canceled or an error occurs. It is recommended to run this function in a separate goroutine.

func (*Client) SendMessages

func (c *Client) SendMessages(
	ctx context.Context,
	params *SendMessagesParams,
	body io.Reader,
) error

SendMessages sends a message to the agrirouter API.

The body of the request must be a valid payload of agrirouter message.

type ClientOption

type ClientOption = func(*Client) error

ClientOption is a type for options that can be passed to the agrirouter client.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient allows to set a custom HTTP client for the agrirouter client. This client will be used for all API calls, but not for fetching file payloads.

func WithPayloadsHTTPClient

func WithPayloadsHTTPClient(httpClient PayloadsHTTPClient) ClientOption

WithPayloadsHTTPClient allows to set a custom HTTP client for fetching payloads.

func WithRequestEditorFn

func WithRequestEditorFn(fn RequestEditorFn) ClientOption

WithRequestEditorFn allows to set a custom request editor function to modify request before sending it. This will not apply to requests when fetching file payloads, only to agrirouter API calls.

type Endpoint

type Endpoint = internal_models.Endpoint

Endpoint is the structure representing an agrirouter endpoint.

type EndpointCapability

type EndpointCapability = internal_models.EndpointCapability

EndpointCapability is the structure representing an endpoint's capability.

It defines what endpoint can do, such as sending or receiving messages of specific types.

type EndpointCapabilityDirection

type EndpointCapabilityDirection = internal_models.EndpointCapabilityDirection

EndpointCapabilityDirection represents the direction of an endpoint's capability.

It indicates whether the endpoint can send, receive, or both send and receive messages of a specific type.

type EndpointSubscription

type EndpointSubscription = internal_models.EndpointSubscription

EndpointSubscription is the structure representing an endpoint's subscription.

It defines which message types the endpoint is subscribed to, meaning it can receive messages of those types in case if sending endpoint has published them.

type EndpointType

type EndpointType = internal_models.EndpointType

EndpointType represents the type of an agrirouter endpoint.

There are three main types of endpoints: 1. communication_unit: Represents devices installed inside vehicles or machines. 2. virtual_communication_unit: Represents virtual devices communicating via their own cloud services. 3. farming_software: Represents farming software applications, typically cloud-based.

type File

type File struct {
	ReceivingEndpointID uuid.UUID // ReceivingEndpointID is the UUID of the endpoint that received the file
	Payload             io.Reader // Payload is the file payload as a stream
	Filename            *string   // Filename is optional as sent by sender endpoint
}

File represents a file received from agrirouter.

Typically files would have larger payloads than messages, so the payload is provided as an io.Reader to allow streaming.

type Message

type Message struct {
	MessageType         string    // MessageType is the URN type of the message
	Payload             []byte    // Payload is the raw message payload
	AppMessageID        string    // AppMessageID is the ID assigned by the sending endpoint
	ReceivingEndpointID uuid.UUID // ReceivingEndpointID is the UUID of the endpoint that received the message
	Filename            *string   // Filename is optional as sent by sender endpoint
}

Message represents a message received from agrirouter.

type MessageHandler

type MessageHandler func(ctx context.Context, message *Message)

MessageHandler is a function that handles a received message.

type MessageReceivedEventData

type MessageReceivedEventData = internal_models.MessageReceivedEventData

MessageReceivedEventData represents the data received in a MessageReceived event.

It contains information about the received message, including its type and payload URI. This event would typically be followed by fetching the actual message payload from the provided URI and processing it accordingly (e.g. decoding, storing, or acting upon the message content).

type PayloadsHTTPClient

type PayloadsHTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

PayloadsHTTPClient is an interface for an HTTP client that can be used to fetch payloads.

type PutEndpointParams

type PutEndpointParams = internal_models.PutEndpointParams

PutEndpointParams contains parameters to create or update an endpoint.

type PutEndpointRequest

type PutEndpointRequest = internal_models.PutEndpointRequest

PutEndpointRequest is the request structure for creating or updating an endpoint.

type RequestEditorFn

type RequestEditorFn = oapi.RequestEditorFn

RequestEditorFn is a function that can modify the request before it is sent.

type SendMessagesParams

type SendMessagesParams = internal_models.SendMessagesParams

SendMessagesParams contains parameters to send a message.