release v0.3.0

.github/workflows/build.yml

@@ -0,0 +1,36 @@
+name: Bus
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Extract tag version
+        id: tag_version
+        run: echo "VALUE=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Extract git commit hash
+        id: git_commit
+        run: echo "VALUE=$(git rev-list -1 HEAD)" >> $GITHUB_OUTPUT
+
+      - name: build and deploy
+        env:
+          VERSION: ${{ steps.tag_version.outputs.VALUE }}
+          GIT_COMMIT: ${{ steps.git_commit.outputs.VALUE }}
+        run: |
+          docker build \
+            --build-arg GIT_COMMIT=${{ env.GIT_COMMIT }} \
+            --build-arg VERSION=${{ env.VERSION }} \
+            --no-cache \
+            --progress=plain \
+            -t ellato/bus:${{ env.VERSION }} -t ellato/bus:latest .
+
+          echo ${{ secrets.ELLA_DOCKER_TOKEN }} | docker login -u ellato --password-stdin
+          docker push ellato/bus:${{ env.VERSION }}
+          docker push ellato/bus:latest

Dockerfile

@@ -0,0 +1,29 @@
+###############################################################################
+### build stage 
+###############################################################################
+FROM golang:1.23-alpine3.20 AS builder
+
+## INSTALL DEPENDENCIES
+RUN apk add --update --no-cache curl git make musl-dev gcc bash
+
+WORKDIR /src
+
+COPY . .
+
+## TEST GO UNIT TESTS
+RUN go test -race -timeout 100s ./... -v
+
+ARG GIT_COMMIT
+ARG VERSION
+
+## BUILD API 
+RUN go build -ldflags="-w -s -X main.GitCommit=${GIT_COMMIT} -X main.Version=${VERSION}" -o ./bin/bus cmd/bus/main.go
+
+###############################################################################
+### run stage
+###############################################################################
+FROM alpine:3.20
+COPY --from=builder /src/bin/bus ./bus
+
+EXPOSE 2021
+CMD ["./bus", "server"]

README.md

@@ -7,19 +7,89 @@
 ╚═════╝░░╚═════╝░╚═════╝░
 ```
 
-# Introduction
+# Bus: A Persistent and High-Performance Message Bus
 
-`bus` is a persistent message bus designed for simplicity and flexibility.
+`bus` is a robust, persistent message bus designed to streamline event handling with simplicity and flexibility. Based on [task](https://ella.to/task), a task runner, [solid](https://ella.to/solid), a signal/broadcast library, and [immuta](https://ella.to/immuta), an append-only log, `bus` delivers high performance, intuitive APIs, and resilient message persistence.
 
-# Feature
+## Key Features
 
-- [x] Support subject pattern matching
-- [x] Support ephemeral and durable consumers
-- [x] Support durable queues to distribute the queue
-- [x] Support and configure time to Redelivery in case of failure
-- [x] Based on Server Sent Event and Http, it can be use and integrate with many languages and support on browsers
-- [x] Support Request / Response pattern
-- [x] Support N number of confirm acks, for syncrhoization of data
+- ✅ **Persistent Event Storage** - Ensures message durability and reliability with a persistent log.
+- ✅ **Pattern Matching on Subjects** - Supports wildcard patterns like `a.*.b` or `a.>` to route events dynamically.
+- ✅ **Request/Reply Pattern** - Easily implement request-response communication with in-built support.
+- ✅ **HTTP and Server-Sent Events (SSE)** - Uses both standard HTTP and SSE for flexible, web-friendly transport.
+- ✅ **Multi-Consumer Confirmation** - Allows publishers to confirm when an event is acknowledged by a specified number of consumers.
+- ✅ **Ergonomic, Idiomatic API** - Designed with simplicity, adhering closely to Golang conventions for ease of use.
+- ✅ **High Performance** - Optimized for rapid event persistence and delivery.
+- ✅ **Redelivery and Acknowledgement** - Provides automatic message redelivery and various acknowledgement strategies for reliability.
+- ✅ **CLI for Debugging** - Comes with a command-line interface to publish, consume, and debug events easily.
+
+## Installation
+
+To install `bus`, use:
+
+```shell
+go get ella.to/bus@v0.3.0
+```
+
+## Basic Example
+
+At its core, bus is a pub/sub library, enabling asynchronous communication between publishers and subscribers. Here’s how to publish an event after creating a client
+
+```golang
+package main
+
+import (
+	"context"
+
+	"ella.to/bus"
+)
+
+func main() {
+	client := bus.NewClient("http://localhost:2021")
+
+	ctx := context.Background()
+
+	// publish an event to subject "a.b.c" with data "hello world"
+	err := client.Put(
+		ctx,
+		bus.WithSubject("a.b.c"),
+		bus.WithData("hello world"),
+	).Error()
+	if err != nil {
+		panic(err)
+	}
+
+	// subscribe to subject "a.b.c" and since subscription is blocking
+	// we can use range to iterate over the events. For every event we
+	// need to ack it. If ack is not called, the event will be redelivered.
+	// Since an event is already published, we start from the oldest event by passing bus.WithStartFrom(bus.StartOldest) options.
+	for event, err := range client.Get(
+        ctx,
+        bus.WithSubject("a.b.c"),
+        bus.WithStartFrom(bus.StartOldest),
+    ) {
+		if err != nil {
+			panic(err)
+		}
+
+		// do something with the event
+		// e.g. print the data
+		println(string(event.Payload))
+
+		// ack the event
+		if err := event.Ack(ctx); err != nil {
+			panic(err)
+		}
+
+		// since there is only one event, we can break the loop
+		break
+	}
+}
+```
+
+## More Examples
+
+for more examples, checkout examples folder
 
 # Reference