sdk

README

SDK

This module will help you to quickly integrate with the API gateway.

Installation

Install SDK to your Go project.

go get github.com/TheUnitedCoders/devpost-auth0-api-gateway/pkg/sdk

Example of usage

1. SDK Initialization. Create a context for working with the SDK and initialize it with the main parameters.

s, err := sdk.New(sdk.NewOptions{
    ServerAddress: ":8001",
    Auth0Domain:   "<AUTH0_DOMAIN>",
    Auth0Audience: "<AUTH0_AUDIENCE>",
    M2MValidation: true,
    GlobalHandlerSettings: sdk.HandlerSettings{
      AuditEnabled:           true,
      RequiredAuthentication: true,
    },
})
if err != nil {
	slog.Error("Failed to init SDK", slog.String("error", err.Error()))
    return
}

1. Register method handlers with specific settings for each method:

err := s.RegisterHandler(sdk.Handler{
    Method: "handler",
    HandlerSettings: sdk.HandlerSettings{
        RateLimiterDescription: &sdk.RateLimiterDescription{
            By:    sdk.RateLimitDescriptionBySubjectId, // Limit by user ID
            Rate:  1, // Number of requests per minute
            Burst: 1, // Burst value
            Period: time.Minute, // Time period
        },
        RequiredPermissions: []string{"read:greeting"}, // Required access permissions
    },
    AllowedHTTPMethods: []sdk.HTTPMethod{sdk.HTTPMethodGet},
    ProcessFunc:        greetingProcess,
})

if err != nil {
    slog.Error("Failed to register greeting handler", slog.String("error", err.Error()))
    return
}

1. Define the request processing function that will execute the processing logic and return a response:

func greetingProcess(ctx context.Context, req *sdk.ProcessRequest) (*sdk.ProcessResponse, error) {
    name := req.Query.Get("name")
    if name == "" {
        name = "unknown :("
    }

    return &sdk.ProcessResponse{
        Body: []byte(fmt.Sprintf(`{"msg": "hello from greeting-service to %s with auth0 ID %s"}`, 
            name, req.SubjectInformation.ID)),
        StatusCode: http.StatusOK,
    }, nil
}

1. Running the Service

if err = s.Run(ctx); err != nil {
    slog.Error("Failed to run SDK", slog.String("error", err.Error()))
}

The full example of usage can be found here. Also, full documentation available here.

Documentation

Index

• Variables
• type HTTPMethod
  • func ParseHTTPMethod(name string) (HTTPMethod, error)
  • func (x HTTPMethod) IsValid() bool
  • func (x HTTPMethod) String() string
• type Handler
• type HandlerFunc
• type HandlerSettings
• type NewOptions
• type ProcessRequest
• type ProcessResponse
• type RateLimitDescriptionBy
  • func ParseRateLimitDescriptionBy(name string) (RateLimitDescriptionBy, error)
  • func (x RateLimitDescriptionBy) IsValid() bool
  • func (x RateLimitDescriptionBy) String() string
• type RateLimiterDescription
• type SDK
  • func New(opts NewOptions) (*SDK, error)
  • func (s *SDK) RegisterHandler(h Handler) error
  • func (s *SDK) Run(ctx context.Context) error
• type SubjectInformation

Variables

var ErrInvalidHTTPMethod = errors.New("not a valid HTTPMethod")

var ErrInvalidRateLimitDescriptionBy = errors.New("not a valid RateLimitDescriptionBy")

Types

type HTTPMethod

type HTTPMethod uint8

HTTPMethod ... ENUM(unspecified, get, put, post, delete, patch)

const (
	// HTTPMethodUnspecified is a HTTPMethod of type Unspecified.
	HTTPMethodUnspecified HTTPMethod = iota
	// HTTPMethodGet is a HTTPMethod of type Get.
	HTTPMethodGet
	// HTTPMethodPut is a HTTPMethod of type Put.
	HTTPMethodPut
	// HTTPMethodPost is a HTTPMethod of type Post.
	HTTPMethodPost
	// HTTPMethodDelete is a HTTPMethod of type Delete.
	HTTPMethodDelete
	// HTTPMethodPatch is a HTTPMethod of type Patch.
	HTTPMethodPatch
)

func ParseHTTPMethod

func ParseHTTPMethod(name string) (HTTPMethod, error)

ParseHTTPMethod attempts to convert a string to a HTTPMethod.

func (HTTPMethod) IsValid

func (x HTTPMethod) IsValid() bool

IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values

func (HTTPMethod) String

func (x HTTPMethod) String() string

String implements the Stringer interface.

type Handler

type Handler struct {
	Method string
	HandlerSettings
	AllowedHTTPMethods []HTTPMethod
	ProcessFunc        HandlerFunc
}

Handler ...

type HandlerFunc

type HandlerFunc func(ctx context.Context, req *ProcessRequest) (*ProcessResponse, error)

HandlerFunc ...

type HandlerSettings

type HandlerSettings struct {
	AuditEnabled           bool
	RateLimiterDescription *RateLimiterDescription
	RequiredAuthentication bool
	RequiredPermissions    []string
}

HandlerSettings ...

type NewOptions

type NewOptions struct {
	ServerAddress         string
	Auth0Domain           string
	Auth0Audience         string
	M2MValidation         bool
	GlobalHandlerSettings HandlerSettings
	Handlers              []Handler
	ServerCloseTimeout    time.Duration
	Logger                *slog.Logger
}

NewOptions ...

type ProcessRequest

type ProcessRequest struct {
	HTTPMethod         HTTPMethod
	Path               string
	Query              url.Values
	Body               []byte
	Headers            http.Header
	SubjectInformation *SubjectInformation
}

ProcessRequest ...

type ProcessResponse

type ProcessResponse struct {
	Body       []byte
	StatusCode int
	Headers    http.Header
}

ProcessResponse ...

type RateLimitDescriptionBy

type RateLimitDescriptionBy uint8

RateLimitDescriptionBy ... ENUM(ip, subject_id)

const (
	// RateLimitDescriptionByIp is a RateLimitDescriptionBy of type Ip.
	RateLimitDescriptionByIp RateLimitDescriptionBy = iota
	// RateLimitDescriptionBySubjectId is a RateLimitDescriptionBy of type Subject_id.
	RateLimitDescriptionBySubjectId
)

func ParseRateLimitDescriptionBy

func ParseRateLimitDescriptionBy(name string) (RateLimitDescriptionBy, error)

ParseRateLimitDescriptionBy attempts to convert a string to a RateLimitDescriptionBy.

func (RateLimitDescriptionBy) IsValid

func (x RateLimitDescriptionBy) IsValid() bool

IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values

func (RateLimitDescriptionBy) String

func (x RateLimitDescriptionBy) String() string

String implements the Stringer interface.

type RateLimiterDescription

type RateLimiterDescription struct {
	By     RateLimitDescriptionBy
	Rate   uint64
	Burst  uint64
	Period time.Duration
}

RateLimiterDescription ...

type SDK

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

SDK that helps integrate with api-gateway.

func New

func New(opts NewOptions) (*SDK, error)

New returns new SDK with provided options.

func (*SDK) RegisterHandler

func (s *SDK) RegisterHandler(h Handler) error

RegisterHandler in SDK. All registrations must be done before Run.

func (*SDK) Run

func (s *SDK) Run(ctx context.Context) error

Run gRPC server.

type SubjectInformation

type SubjectInformation struct {
	ID          string
	Permissions []string
}

SubjectInformation ...