README
¶
Wrapper
The Wrapper package provides adapters and abstractions for external libraries, allowing standardized and flexible integration with the Boost framework. This package is essential for ensuring interoperability and consistency when using third-party libraries.
Overview
Wrapper acts as an abstraction layer between application code and external libraries, offering consistent interfaces and facilitating the replacement of underlying implementations without affecting client code. This promotes code maintainability and testability.
Main Components
Cache
The cache subpackage provides abstractions for caching systems, including:
- Codec: Serializers and deserializers for different formats (binary, gob, json, string)
- Driver: Implementations for different cache providers (Redis, BigCache, FreeCache)
- Plugins: Extensions for additional cache functionalities
This component allows efficient storage and retrieval of cached data, with support for multiple formats and backends.
Config
The config subpackage offers a unified interface for application configuration, with support for:
- Multiple configuration sources (files, environment variables, flags)
- Different formats (YAML, JSON, ENV)
- Value validation and transformation
This facilitates configuration management across different environments and deployment scenarios.
Drivers: contrib/knadh/koanf/v1 (wired by boost.Start()) and
contrib/knadh/koanf/v2 (set with config.Set(koanf.New())).
Log
The log subpackage provides abstractions for logging systems, with support for:
- Multiple log levels (debug, info, warn, error)
- Different output formats (text, JSON, CloudWatch)
- Integration with popular libraries (Zap, Zerolog, Logrus)
This component allows consistent and configurable recording of application events and information.
Publisher
The publisher subpackage offers abstractions for message publishing/subscription systems, including:
- Drivers for different providers (Google Cloud Pub/Sub, Kafka, NATS, AWS SNS, SQS and Kinesis)
- Middleware for message interception and modification
- Utilities for monitoring and metrics
This facilitates asynchronous communication between components and services.
Publisher.Publish returns an error when the driver fails or when any event
fails. A per-event failure comes back as one Internal error that joins every
failed event's error (tagged with its event ID), so errors.Is/errors.As
still reach each cause. Middlewares keep receiving the per-event
[]PublishOutput (with each event's Error) and a nil chain error; the
aggregate error is built after the middleware chain.
The Kafka driver (driver/contrib/confluentinc/confluent-kafka-go/v2) returns
only after every produced message has its delivery report, bounded by the
ctx passed to Publish: a failed delivery (TopicPartition.Error, e.g.
message timeout or unknown partition) or a ctx that ends before the report
arrives becomes that event's Error. Reports go to a delivery channel per
Publish call, so they no longer reach the producer's Events() channel; the
driver logs each delivery at its own log.level.
The kafka-go driver (driver/contrib/segmentio/kafka-go/v0, on the writer of
factory/contrib/segmentio/kafka-go/v0) writes all events in one
WriteMessages, in CloudEvents binary mode: the data is the value, the
attributes and extensions are ce_* headers (ce_time in RFC3339) plus
content-type. The topic is the event subject; the key is the key
extension, else partitionkey, else the event ID. An event without subject,
or one kafka-go reports in kafka.WriteErrors, gets its own Error; any
other write error fails every event of the call. fx:
fx/modules/wrapper/publisher/driver/contrib/segmentio/kafka-go/v0, switched by
boost.wrapper.publisher.driver.kafkago.enabled.
The AWS drivers (driver/contrib/aws/{sns,sqs,kinesis}/v1, on the clients of
factory/contrib/aws/aws-sdk-go-v2/v1/client/...) send the event subject as
the destination: the SNS topic ARN, the SQS queue name (URL resolved and
cached) or the Kinesis stream name. The payload is the whole CloudEvent as
JSON, or only its data when the target extension is data
(util.Payload). SQS takes MessageGroupId from the group extension;
Kinesis takes the partition key from the partitionkey extension (the event
ID without it) and puts the events of one stream in one PutRecords, so a
failed stream fails all its events. Retries are the AWS SDK retryer's
(boost.factory.aws.retryer.*). fx: fx/modules/wrapper/publisher/driver/contrib/aws/<service>/v1,
switched by boost.wrapper.publisher.driver.<service>.enabled.
How to Use
To use the Wrapper package in your application:
- Import the specific subpackage containing the desired abstraction
- Configure the specific implementation you want to use
- Use the abstract interface in your code, independent of the underlying implementation
Integration with Other Packages
Wrapper integrates with other components of the Boost framework:
- Bootstrap: For component initialization and configuration
- Factory: For creating instances of specific implementations
- Extra: For additional functionalities like middleware
Extensibility
The Wrapper package was designed to be easily extensible. To add support for new libraries:
- Create a new subpackage in
contribwith the name of the library - Implement the necessary abstract interfaces
- Add appropriate tests and documentation
Contribution
Contributions to the Wrapper package are welcome. When contributing, make sure to follow the code standards and add appropriate tests for new functionalities.
Directories
¶
| Path | Synopsis |
|---|---|
|
codec/contrib/shamaton/msgpack/v3
Package msgpack is a wrapper/cache codec on github.com/shamaton/msgpack/v3.
|
Package msgpack is a wrapper/cache codec on github.com/shamaton/msgpack/v3. |
|
examples/freecache
command
|
|
|
examples/freecache-binary
command
|
|
|
examples/multi
command
|
|
|
examples/plugin
command
|
|
|
Package config provides a wrapper around koanf.
|
Package config provides a wrapper around koanf. |
|
contrib/knadh/koanf/v2
Package koanf is the boost config driver on koanf v2.
|
Package koanf is the boost config driver on koanf v2. |
|
examples/env
command
|
|
|
examples/env_file
command
|
|
|
Package log provides a generic interface around loggers.
|
Package log provides a generic interface around loggers. |
|
driver/contrib/aws/kinesis/v1
Package kinesis is a publisher driver that puts each event in the Kinesis stream named by the event subject.
|
Package kinesis is a publisher driver that puts each event in the Kinesis stream named by the event subject. |
|
driver/contrib/aws/sns/v1
Package sns is a publisher driver that sends each event to the SNS topic whose ARN is the event subject.
|
Package sns is a publisher driver that sends each event to the SNS topic whose ARN is the event subject. |
|
driver/contrib/aws/sqs/v1
Package sqs is a publisher driver that sends each event to the SQS queue named by the event subject.
|
Package sqs is a publisher driver that sends each event to the SQS queue named by the event subject. |