Release/v0.3

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @ahmedkamalio

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Report something that doesn't work as documented
+title: "[bug] "
+labels: ["bug"]
+---
+
+## Describe the bug
+
+A clear, concise description of what the bug is.
+
+## Reproduction
+
+Minimal steps (or a short Go snippet) that reproduce the problem:
+
+```go
+// ...
+```
+
+## Expected behavior
+
+What you expected to happen.
+
+## Actual behavior
+
+What actually happened. Include the full error / stack trace if available.
+
+## Environment
+
+- **gas-queue version:** (e.g. v0.2.32 — check `go list -m github.com/gasmod/gas-queue`)
+- **Go version:** `go version`
+- **OS / arch:** (e.g. macOS arm64, Ubuntu 24.04 amd64)
+- **Related gasmod modules + versions:** (if any)
+
+## Additional context
+
+Anything else that might help — logs, config snippets, screenshots.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/gasmod/gas-queue/security/advisories/new
+    about: Please report security issues privately via GitHub Security Advisories. See SECURITY.md.
+  - name: Question / discussion
+    url: https://github.com/orgs/gasmod/discussions
+    about: For "how do I do X" questions, open a discussion instead of an issue.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature request
+about: Suggest a new feature or API change
+title: "[feature] "
+labels: ["enhancement"]
+---
+
+## Problem
+
+What user-facing problem are you trying to solve? Describe the use case before
+the proposed solution — small, well-scoped problems get reviewed faster.
+
+## Proposed solution
+
+What change to the API or behavior would solve it? Pseudo-code is welcome:
+
+```go
+// ...
+```
+
+## Alternatives considered
+
+What other approaches did you weigh, and why did you discard them?
+
+## Additional context
+
+Links to related issues, prior art in other libraries, or anything else useful.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## Summary
+
+<!-- One or two sentences on what this PR changes and why. -->
+
+## Type of change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing behavior to change)
+- [ ] Documentation only
+- [ ] Refactor / internal cleanup
+
+## Checklist
+
+- [ ] Conventional commit message (`feat:`, `fix:`, `docs:`, ...).
+- [ ] Commits are signed off (`git commit -s`).
+- [ ] New behavior is covered by tests; bug fixes include a regression test.
+- [ ] `go test -race ./...` passes locally.
+- [ ] `make lint` (or `golangci-lint run`) passes locally.
+- [ ] Public API changes are reflected in package doc comments and `CHANGELOG.md`.
+
+## Related issues
+
+<!-- e.g. "Closes #123" or "Related to #456" -->

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/release.yml

@@ -9,22 +9,17 @@ permissions:
   contents: write
 
 jobs:
-  lint_test_release:
+  lint:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up Go
         uses: actions/setup-go@v6
         with:
           go-version: '1.26'
 
-      - name: Configure private modules
-        run: |
-          go env -w GOPRIVATE="github.com/gasmod/*"
-          git config --global url."https://x-access-token:${{ secrets.GH_PAT }}@github.com/".insteadOf "https://github.com/"
-
       - name: Run golangci-lint
         uses: golangci/golangci-lint-action@v9
         with:
@@ -36,10 +31,11 @@ jobs:
         run: go test -v -race ./...
 
       - name: Create Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           name: Release ${{ github.ref_name }}
           draft: false
           prerelease: false
+          generate_release_notes: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -11,22 +11,17 @@ permissions:
   contents: read
 
 jobs:
-  lint_test:
+  lint-test:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up Go
         uses: actions/setup-go@v6
         with:
           go-version: '1.26'
 
-      - name: Configure private modules
-        run: |
-          go env -w GOPRIVATE="github.com/gasmod/*"
-          git config --global url."https://x-access-token:${{ secrets.GH_PAT }}@github.com/".insteadOf "https://github.com/"
-
       - name: Run golangci-lint
         uses: golangci/golangci-lint-action@v9
         with:

CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-03
+
+First open source release. Versions prior to 0.3.0 were developed in a private
+repository; this entry summarizes the package as published.
+
+### Added
+
+- **`sqs.Service`** — an AWS SQS-backed queue implementing `gas.Service`,
+  `gas.JobQueueProvider`, and `gas.ReadyReporter` (`CheckReady` errors before
+  `Init` and after `Close`, so callers can drain traffic during graceful
+  shutdown). Constructed via `sqs.New()` for DI-based injection.
+- **Enqueue options** — `gas.WithDelay` (initial visibility delay),
+  `gas.WithGroupID` and `gas.WithDedupeID` (FIFO ordering and
+  deduplication), and `gas.WithJobAttributes` (custom message attributes),
+  applied through `gas.ApplyEnqueueOptions`.
+- **Dequeue with long-polling** — `Dequeue` clamps `maxMessages` to SQS's
+  1-10 range (logging a warning if clamped) and falls back to the
+  configured `Queue.WaitTimeSeconds` when no explicit wait is given. Both
+  system attributes (e.g. `SentTimestamp`, `ApproximateReceiveCount`) and
+  message attributes are merged onto the returned `gas.Job.Attributes`.
+- **Ack/Nack semantics** — `Ack` deletes the message from the queue; `Nack`
+  zeroes the message's visibility timeout via `ChangeMessageVisibility`,
+  making it immediately available for redelivery.
+- **Configuration** — `Config`/`Settings`, bindable via `gas.ConfigProvider`
+  when `WithConfig` is not supplied, covering `Queue.Region`,
+  `Queue.Endpoint` (custom endpoint for ElasticMQ or other SQS-compatible
+  services), `Queue.AccessKeyID`/`Queue.SecretAccessKey` (falling back to
+  the default AWS credential chain when unset), `Queue.VisibilityTimeout`,
+  and `Queue.WaitTimeSeconds`, all validated on `Init`.
+- **`WithClient`** to inject a pre-configured SQS client (or any type
+  satisfying the minimal `sqsClient` interface), and **`Client()`** to
+  access the underlying `*sqs.Client` directly for advanced operations
+  (`CreateQueue`, `PurgeQueue`, `GetQueueAttributes`, etc.) beyond the
+  `gas.JobQueueProvider` interface.
+- **`queue.ErrClosed`** sentinel error, returned by `Enqueue`, `Dequeue`,
+  `Ack`, `Nack`, and `CheckReady` once the service has been closed.
+- **`queuetest` package** with `MockQueue`, a configurable mock of
+  `gas.JobQueueProvider` that records calls (`CallCount`, `Reset`) and
+  delegates to per-method `Fn` fields when set.
+
+[Unreleased]: https://github.com/gasmod/gas-queue/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/gasmod/gas-queue/releases/tag/v0.3.0

CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Code of Conduct
+
+## Scope
+
+This project has one maintainer today. This document sets the conduct expected in project spaces (the repository, issues, pull requests, discussions, and any project channel) and states what happens when that conduct isn't met. It applies to everyone who participates, maintainer included.
+
+## Standards
+
+The work here is technical. Direct criticism of code, design, and decisions is expected and welcome; that is the point of an open repository. Being wrong is not a violation. Changing your mind is not a violation. Disagreeing with the maintainer is not a violation.
+
+The line is conduct toward people, not positions. The following are out of bounds:
+
+- Personal attacks, insults, or demeaning comments aimed at a person rather than their argument.
+- Harassment of any kind, public or private, including sustained disruption after being asked to stop.
+- Sexualized language, imagery, or advances.
+- Publishing someone's private information without their consent.
+- Deliberate bad-faith participation: knowingly false reports, sabotage, or trolling.
+
+If you are unsure whether something crosses the line, the test is whether it is aimed at the work or at the person.
+
+## Enforcement
+
+Reports go to **contact@ahmedkamal.io**. Include what happened, where, and links if they exist. There is no committee and no response-time guarantee, but every report is read and reviewed.
+
+Because this is a solo project, enforcement is at the maintainer's discretion. There is no appeals board and no pretense of one. What is committed here is that action is proportionate to what happened, and applied to conduct rather than to whose side of a technical argument someone was on. In rough order of severity:
+
+1. A private note that the conduct is not acceptable, stating what needs to change.
+2. A public correction on the thread, with edits or removal of the offending content.
+3. A temporary block from project spaces.
+4. A permanent block.
+
+Severity, repetition, and whether the behavior stops determine which applies. A single serious violation can go straight to a block without the earlier steps.

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to Gas
+
+Thanks for your interest in contributing!
+
+## Filing issues
+
+- **Bugs:** include Go version, OS, a minimal reproducer, and what you expected vs. what happened.
+- **Features:** describe the use case before the proposed API. Small, focused proposals get reviewed faster.
+
+## Submitting changes
+
+1. Fork the repo and create a topic branch.
+2. Run tests locally: `go test -race ./...`
+3. Run lint: `make lint` (or `golangci-lint run`).
+4. Use **conventional commits** (`feat:`, `fix:`, `docs:`, `refactor:`, etc.).
+5. **Sign off** every commit (`git commit -s`) — required by the DCO.
+6. Open a PR against `main`. Keep PRs focused; one logical change per PR.
+
+## Tests
+
+- New features need tests. Bug fixes need a regression test.
+- Prefer the table-driven `t.Run("name", func(t *testing.T) { ... })` style used throughout.
+- Keep tests parallel (`t.Parallel()`) unless they touch shared state.
+
+## Code style
+
+- Follow the existing patterns in the package you're touching.
+- Document exported APIs. Doc comments should start with the symbol name.
+
+## Reporting security issues
+
+See [SECURITY.md](SECURITY.md). **Do not** open public issues for security reports.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Kamal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -21,9 +21,9 @@ build: ## Build the binary
 
 # Linting and formatting
 lint: ## Run linters
-	@which golangci-lint > /dev/null || (echo "Installing golangci-lint..." && go install github.com/golangci/golangci-lint/cmd/golangci-lint@2.4.0)
+	@which golangci-lint > /dev/null || (echo "Installing golangci-lint..." && go install github.com/golangci/golangci-lint/cmd/golangci-lint@v2.11.0)
 	golangci-lint run
 
 fmt: ## Format code
-	@which golangci-lint > /dev/null || (echo "Installing golangci-lint..." && go install github.com/golangci/golangci-lint/cmd/golangci-lint@2.4.0)
+	@which golangci-lint > /dev/null || (echo "Installing golangci-lint..." && go install github.com/golangci/golangci-lint/cmd/golangci-lint@v2.11.0)
 	golangci-lint fmt

README.md

@@ -1,5 +1,7 @@
 # gas-queue
 
+[![Test](https://github.com/gasmod/gas-queue/actions/workflows/test.yml/badge.svg)](https://github.com/gasmod/gas-queue/actions/workflows/test.yml) [![Go Reference](https://pkg.go.dev/badge/github.com/gasmod/gas-queue.svg)](https://pkg.go.dev/github.com/gasmod/gas-queue) ![Go Version](https://img.shields.io/github/go-mod/go-version/gasmod/gas-queue) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
 Job queue service for the [Gas](https://github.com/gasmod/gas) ecosystem. Provides a `gas.JobQueueProvider` implementation
 backed by AWS SQS, plus a test mock for use in unit tests.
 

SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported versions
+
+The Gas ecosystem is pre-1.0. Only the latest released minor version of each module receives security fixes.
+
+## Reporting a vulnerability
+
+**Do not** file a public GitHub issue for security vulnerabilities.
+
+Please use [GitHub's private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
+on this repository to report the issue, or email **contact@ahmedkamal.io** with:
+
+- A description of the vulnerability and its impact.
+- Steps to reproduce, or a proof-of-concept.
+- The affected version(s) and module(s).
+- Any suggested mitigations, if known.
+
+You can expect:
+
+- An initial acknowledgement within **7 days**.
+- A coordinated disclosure timeline once the issue is triaged.
+- Credit in the release notes if you wish (or anonymity if you prefer).

context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/gasmod/gas-queue",
+  "public_key": "pk_xKSOHOvzsiCF81sgv3HPO"
+}

doc.go

@@ -0,0 +1,6 @@
+// Package queue provides async job queue processing with AWS SQS. Concrete implementations live in the sqs sub-package.
+//
+// See the module README for usage examples and design rationale.
+//
+// SPDX-License-Identifier: MIT
+package queue