initial commit

Signed-off-by: Dusan Malusev <dusan@dusanmalusev.dev>

Author: CodeLieutenant

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: Go
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  build:
+    name: Lint Test and Build
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.25'
+          check-latest: true
+      - name: Set up gotestfmt
+        uses: GoTestTools/gotestfmt-action@v2
+        with:
+          repo: gotestfmt
+      - name: Unit Tests
+        run: |
+          sudo apt install libnss3-tools
+          make setup
+          make test
+      - name: Linting
+        uses: golangci/golangci-lint-action@v8
+      - name: Run Gosec
+        uses: securego/gosec@master
+        with:
+          args: ./...
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: CodeLieutenant/utils

.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  packages: write
+  issues: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Get Tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: olegtarasov/get-tag@v2.1.3
+        id: version_tag
+        with:
+          tagRegex: "v(.*)"
+      - name: Upload Release Asset
+        uses: softprops/action-gh-release@v1
+        id: release
+        with:
+          name: "v${{ steps.version_tag.outputs.tag }}"
+          tag_name: "v${{ steps.version_tag.outputs.tag }}"
+          generate_release_notes: true
+          append_body: true
+          prerelease: false
+          fail_on_unmatched_files: true
+      - name: "Generate release changelog"
+        uses: heinrichreimer/action-github-changelog-generator@v2.3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          author: true
+          releaseUrl: ${{ steps.release.outputs.url }}
+          issues: false
+          pullRequests: true
+      - uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "Update CHANGELOG.md"
+          branch: master
+          commit_options: "--no-verify --signoff"
+          file_pattern: CHANGELOG.md

.gitignore

@@ -0,0 +1,7 @@
+certs/
+bin/
+coverage.txt
+coverage.out
+.DS_Store
+*.html
+*.log

Makefile

@@ -0,0 +1,85 @@
+SHELL := /usr/bin/env bash
+.DEFAULT_GOAL := help
+.EXPORT_ALL_VARIABLES:
+
+MKCERT_INSTALL_PATH ?= $(HOME)/.local/bin
+MKCERT_VERSION := v1.4.4
+MKCERT_ASSET := mkcert-$(MKCERT_VERSION)-linux-amd64
+MKCERT_URL := https://github.com/FiloSottile/mkcert/releases/latest/download/$(MKCERT_ASSET)
+CERT_DIR ?= ./certs
+HOSTS ?= localhost 127.0.0.1 ::1
+
+
+.PHONY: setup
+setup: install-mkcert mkcert-generate mkcert-generate mkcert-install-ca
+
+
+.PHONY: check
+check: ## Run linters
+	@go tool golangci-lint run
+
+.PHONY: fix
+fix: ## Auto-fix lint issues where possible
+	@go tool golangci-lint run --fix
+
+.PHONY: fieldalign
+fieldalign: ## Apply field alignment fixes
+	@go tool fieldalignment -fix ./pkg/...
+
+.PHONY: fmt
+fmt: ## Run project formatting helpers
+	@go tool golangci-lint fmt
+
+.PHONY: tidy
+tidy: ## Tidy go.mod and download modules
+	go mod tidy
+	go mod download
+
+.PHONY: test
+test: ## Run unit tests with coverage (JSON output piped through gotestfmt)
+	@go test -covermode=atomic -gcflags='all=-N -l' -tags testing -coverprofile=coverage.txt -timeout 5m -json -v ./... 2>&1 | go tool gotestfmt -showteststatus
+
+.PHONY: security
+security: ## Run basic security checks (gosec)
+	go tool gosec ./...
+
+
+# --- Mkcert  -------------------------------
+install-mkcert: ## Install mkcert binary to $(MKCERT_INSTALL_PATH) if missing
+	@if [ ! -f "$(MKCERT_INSTALL_PATH)/mkcert" ]; then \
+	  mkdir -p $(MKCERT_INSTALL_PATH) 2>/dev/null || true; \
+	  echo "Downloading mkcert from $(MKCERT_URL)..."; \
+	  tmp=$$(mktemp -d); \
+	  curl -L --fail -o $$tmp/$(MKCERT_ASSET) "$(MKCERT_URL)"; \
+	  chmod +x $$tmp/$(MKCERT_ASSET); \
+	  mv $$tmp/$(MKCERT_ASSET) $(MKCERT_INSTALL_PATH)/mkcert || { echo "Failed to move mkcert to $(MKCERT_INSTALL_PATH)"; exit 1; }; \
+	  rm -rf $$tmp; \
+	  echo "mkcert installed to $(MKCERT_INSTALL_PATH)/mkcert"; \
+	fi
+
+mkcert-install-ca: install-mkcert ## Install mkcert CA into system trust stores
+	@echo "Installing mkcert CA..."
+	@$(MKCERT_INSTALL_PATH)/mkcert -install
+
+mkcert-generate: mkcert-install-ca ## Generate cert/key for HOSTS into $(CERT_DIR) (usage: make mkcert-generate HOSTS='example.test localhost')
+	@mkdir -p $(CERT_DIR)
+	@echo "Generating cert for: $(HOSTS)"
+	@$(MKCERT_INSTALL_PATH)/mkcert -cert-file $(CERT_DIR)/smtp.crt -key-file $(CERT_DIR)/smtp.key $(HOSTS)
+	@echo "Created $(CERT_DIR)/smtp.crt and $(CERT_DIR)/smtp.key"
+	@$(MKCERT_INSTALL_PATH)/mkcert -cert-file $(CERT_DIR)/local.crt -key-file $(CERT_DIR)/local.key $(HOSTS)
+	@echo "Created $(CERT_DIR)/local.crt and $(CERT_DIR)/local.key"
+
+mkcert-uninstall-ca: install-mkcert ## Uninstall mkcert CA from system trust stores
+	@echo "Uninstalling mkcert CA..."
+	@$(MKCERT_INSTALL_PATH)/mkcert -uninstall || echo "mkcert -uninstall failed (maybe not installed)"
+
+
+.PHONY: clean
+clean: ## Remove build artifacts
+	rm -rf bin/
+	go clean
+
+.PHONY: help
+help:
+	@echo 'UTILS - Available commands:'
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)

bytes.go

@@ -0,0 +1,42 @@
+package utils
+
+import (
+	"math"
+	"slices"
+	"strconv"
+)
+
+type MemorySize uint64
+
+const (
+	KiB MemorySize = 1 << 10
+	MiB MemorySize = 1 << 20
+	GiB MemorySize = 1 << 30
+	TiB MemorySize = 1 << 40
+)
+
+func (m MemorySize) String() string {
+	switch {
+	case m >= TiB:
+		return FormatMemorySize(m, TiB, "TiB")
+	case m >= GiB:
+		return FormatMemorySize(m, GiB, "GiB")
+	case m >= MiB:
+		return FormatMemorySize(m, MiB, "MiB")
+	case m >= KiB:
+		return FormatMemorySize(m, KiB, "KiB")
+	default:
+		return FormatMemorySize(m, 1, "B")
+	}
+}
+
+var largestFloatSize = len(strconv.FormatFloat(math.MaxFloat64, 'f', 0, 64))
+
+func FormatMemorySize(m MemorySize, unit MemorySize, suffix string) string {
+	bytes := make([]byte, 0, len(suffix)+largestFloatSize)
+
+	bytes = strconv.AppendFloat(bytes, float64(m)/float64(unit), 'f', 0, 64)
+	bytes = append(bytes, suffix...)
+
+	return UnsafeString(slices.Clip(bytes))
+}