Getting Started

Getting Started with TypeQueue

The easiest way to get started with TypeQueue is to learn via the "Monolithic" approach, where lambdas are out of the question. During this guide, you'll learn:

• How to setup a Dispatcher
• How to Dispatch Messages
• How to Consume Messages

How to setup a Dispatcher (Pre Requisite)

All items that are dispatched are required to confirm to typesend.SQSAble and be JSON capable:

type ExampleEvent struct {
	typequeue.SQSAble
	Message string `json:"message"`
}

How to setup a Dispatcher

// Optional, if you haven't connected to SQS yet:
sqsClient, err := typequeue_helpers.ConnectToSQS(dml.AWSRegion)
if err != nil {
	panic(err)
}

dispatcher := &typequeue.Dispatcher[*ExampleEvent]{
	SQSClient:         sqsClient,
}

...and that's it! You are now connected and ready to send events to SQS.

How to Dispatch Messages

Important

It is critically important you never require the typequeue.Dispatcher struct, and instead always use the typequeue.TypeQueueDispatcher[*schemas.DispatchedOverdueCall] interface. This will make sense once you read the guide on Testing.

func SendAMessage(dispatcher typequeue.TypeQueueDispatcher[*ExampleEvent]) error {
  ctx := context.WithValue(context.Background(), "trace-id", uuid.NewString()) // critical! All events must be traceable.
	msgID, err := dispatcher.Dispatch(ctx, &ExampleEvent{
	 Message: "Hello world",
	}, "example-queue-name")
	log.Printf("Sent %s", msgID)
	return err
}

Yup, 2 lines of code is really all it takes to send a message.. how nice!

How to Consume Messages

Warning

DO NOT use this code if you are consuming via a Lambda function. Read up on "Consuming in Lambdas" if you plan to consume via Lambda.

consumer := typequeue.Consumer[*ExampleEvent]{
	SQSClient: sqsClient,
	Logger:    logrus.New(), // there is an interface available; should work for most logging solutions. I just like Logrus :)
}

processFn := func(received *ExampleEvent) error {
  log.Println(received)
	return nil
}

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// Run consumer in a goroutine.
go func() {
	opts := typequeue.ConsumerSQSOptions{
		TargetQueue:         "example-queue-name",
		MaxNumberOfMessages: 10, // 10 messages in the batch, individually sent to processFunc
		WaitTimeSeconds:     10, // Poll for 10 seconds
	}
	consumer.Consume(ctx, opts, processFn)
}()

You are now consuming messages, yay!

Acknowledging / Rejecting Messages for Retry

Your consumers processing function should return an error when it is retry eligible.

Any events that have an error will go through your SQS retry system (or DLQ).

Nicely, the processing functions require 0 change when you move to Lambda-land (where messages need to get rejected instead of acknowledged)

References

For additional examples, refer to the test files:

• Dispatch and Consumer Tests: pkg/typequeue_mocks/test
• Lambda Consumer Tests: pkg/typequeue_lambda/test

What Next

• Read up on TESTING-- a super cool powerhouse feature of TypeQueue.
• Read up on Consuming in Lambdas-- slightly different, yet oh so simple.
• Read up on Batch Dispatching-- yup, this package takes care of it for you.
• Check out CrossTalks-- this lets you run your program with full queue support, just without the real SQS interaction.

Using these examples as a guide, you can confidently test your queue-dependent code without connecting to AWS.

Happy Testing!