diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 0000000..65ab99c --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,71 @@ +version: 2.1 + +orbs: + qqq-orb: kingsrook/qqq-orb@0.6.8 + +commands: + configure-package-install: + steps: + - run: + name: Keep package installation unattended + command: | + # These build machines are discarded after the job. + sudo install -d /etc/needrestart/conf.d + printf '%s\n' '$nrconf{restart} = "l";' | sudo tee /etc/needrestart/conf.d/99-qqq-ci.conf >/dev/null + +workflows: + test_only: + jobs: + - qqq-orb/mvn_test_only: + pre-steps: + - configure-package-install + context: [qqq-maven-registry-credentials] + filters: + branches: + ignore: /(develop|release\/.*|hotfix\/.*)/ + + publish_snapshot: + jobs: + - qqq-orb/mvn_publish: + pre-steps: + - configure-package-install + context: [qqq-maven-registry-credentials] + branch_type: snapshot + filters: + branches: + only: [develop] + + publish_release_candidate: + jobs: + - qqq-orb/mvn_publish: + pre-steps: + - configure-package-install + context: [qqq-maven-registry-credentials] + branch_type: release_candidate + filters: + branches: + only: [/release\/.*/] + + publish_release: + jobs: + - qqq-orb/mvn_publish: + pre-steps: + - configure-package-install + context: [qqq-maven-registry-credentials] + branch_type: release + filters: + branches: + ignore: /.*/ + tags: + only: [/v.*/] + + publish_hotfix_release: + jobs: + - qqq-orb/mvn_publish: + pre-steps: + - configure-package-install + context: [qqq-maven-registry-credentials] + branch_type: hotfix + filters: + branches: + only: [/hotfix\/.*/] diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..8db2889 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,20 @@ +# QRun-IO qbit .editorconfig: the Kingsrook layout (3-space indentation, never tabs). +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 3 +tab_width = 3 + +[*.md] +trim_trailing_whitespace = false + +[*.{yml,yaml}] +indent_size = 2 + +[*.{cmd,bat}] +end_of_line = crlf diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..ddf5f61 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +* text=auto eol=lf +*.cmd text eol=crlf +mvnw text eol=lf diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..e7d84f9 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @KofTwentyTwo diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..9878878 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,25 @@ +# Weekly, grouped dependency updates. Minor and patch updates arrive as one PR per ecosystem; +# major updates stay separate so each gets its own review. At most three version-update PRs per +# ecosystem are open at once. Security updates are enabled in the repository settings and are +# not limited by this schedule. +version: 2 +updates: + - package-ecosystem: maven + directory: / + target-branch: develop + schedule: + interval: weekly + open-pull-requests-limit: 3 + groups: + maven-minor-and-patch: + update-types: [minor, patch] + + - package-ecosystem: github-actions + directory: / + target-branch: develop + schedule: + interval: weekly + open-pull-requests-limit: 3 + groups: + github-actions: + patterns: ['*'] diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..796e118 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,46 @@ +# AGENTS.md + +This file provides guidance to Codex when working with code in this repository. + +## Project Overview + +**QBit CDN**: QQQ QBit: put any CDN in front of a QQQ application (portable cache headers, change-driven invalidation, edge statistics, Admin -> CDN app). Design: [QRun-IO/qqq#1084](https://github.com/QRun-IO/qqq/pull/1084) (`docs/specs/2026-10-12-qbit-cdn-design.md`). Implementation in progress. + +## Build Commands + +```bash +./mvnw compile # Compile (always use the wrapper: Maven 3.10 cannot read the parent POM) +./mvnw test # Unit tests +./mvnw verify # Unit tests + JaCoCo gate (thresholds in pom.xml) +``` + +## Architecture + +**Entry point:** `CdnQBitProducer implements QBitMetaDataProducer` in `com.kingsrook.qbits.cdn`. Component producers in this package (and below) are found by package scanning. + +## Naming (owner rule) + +- Tables are lowercase snake_case prefixed with the full qbit name: `cdn_`. The QQQ table name and the backend (SQL) name are identical; possible-value sources take the table name. +- Permissions use the full qbit name: `cdn.` (for example `cdn.view`, `cdn.admin`). +- Qbit data lives in standard, visible QQQ tables, secured by permissions and record security locks, never hidden. +- Processes run as table or record actions, never in the nav. + +## Code Style + +- 3-space indentation, opening braces on the next line, `return (x);`. +- Javadoc flower-box comments (`/*****` with `**` lines) on every class and method. +- Fluent setters (`withX()`). +- Wrapper types (`Integer`, `Boolean`) in config and entities. + +## Dependencies + +- Java 21. +- Parent `com.kingsrook:qbit-build-parent:2.0.0` (qqq 4.0.0). The default-active `qqq-snapshot` profile imports `qqq-bom-pom:4.1.0-RC.4` ahead of it, as in qbit-quick-search (ADR-0007). Remove that activation when the parent moves to 4.1. +- Tests: see pom.xml. + +## Release + +- CircleCI qqq-orb 0.6.8. +- `develop` publishes SNAPSHOTs. +- A `release/*` branch publishes RCs (the orb bumps the version). +- A `v*` tag publishes the release. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9d8b84d --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,8 @@ +# Changelog + +All notable changes to this project are documented here. The format follows Keep a Changelog; versions follow semantic versioning. + +## [0.1.0] - Unreleased + +### Added +- First implementation; see README.md for the tables, permissions and configuration. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..443488d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,46 @@ +# CLAUDE.md + +This file provides guidance to Claude Code when working with code in this repository. + +## Project Overview + +**QBit CDN**: QQQ QBit: put any CDN in front of a QQQ application (portable cache headers, change-driven invalidation, edge statistics, Admin -> CDN app). Design: [QRun-IO/qqq#1084](https://github.com/QRun-IO/qqq/pull/1084) (`docs/specs/2026-10-12-qbit-cdn-design.md`). Implementation in progress. + +## Build Commands + +```bash +./mvnw compile # Compile (always use the wrapper: Maven 3.10 cannot read the parent POM) +./mvnw test # Unit tests +./mvnw verify # Unit tests + JaCoCo gate (thresholds in pom.xml) +``` + +## Architecture + +**Entry point:** `CdnQBitProducer implements QBitMetaDataProducer` in `com.kingsrook.qbits.cdn`. Component producers in this package (and below) are found by package scanning. + +## Naming (owner rule) + +- Tables are lowercase snake_case prefixed with the full qbit name: `cdn_`. The QQQ table name and the backend (SQL) name are identical; possible-value sources take the table name. +- Permissions use the full qbit name: `cdn.` (for example `cdn.view`, `cdn.admin`). +- Qbit data lives in standard, visible QQQ tables, secured by permissions and record security locks, never hidden. +- Processes run as table or record actions, never in the nav. + +## Code Style + +- 3-space indentation, opening braces on the next line, `return (x);`. +- Javadoc flower-box comments (`/*****` with `**` lines) on every class and method. +- Fluent setters (`withX()`). +- Wrapper types (`Integer`, `Boolean`) in config and entities. + +## Dependencies + +- Java 21. +- Parent `com.kingsrook:qbit-build-parent:2.0.0` (qqq 4.0.0). The default-active `qqq-snapshot` profile imports `qqq-bom-pom:4.1.0-RC.4` ahead of it, as in qbit-quick-search (ADR-0007). Remove that activation when the parent moves to 4.1. +- Tests: see pom.xml. + +## Release + +- CircleCI qqq-orb 0.6.8. +- `develop` publishes SNAPSHOTs. +- A `release/*` branch publishes RCs (the orb bumps the version). +- A `v*` tag publishes the release. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..29084f7 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,3 @@ +# Code of Conduct + +See Project level [Code of Conduct](https://github.com/QRun-IO/qqq/blob/develop/CODE_OF_CONDUCT.md) diff --git a/CODE_STYLE.md b/CODE_STYLE.md new file mode 100644 index 0000000..0e6fef2 --- /dev/null +++ b/CODE_STYLE.md @@ -0,0 +1,3 @@ +# Code Style Guide + +* See Project [Code Style Guide](https://github.com/QRun-IO/qqq/blob/develop/CODE_STYLE.md) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..878bd2e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,6 @@ +# Contributing to QBit CDN + +* See Project [Contributing](https://github.com/QRun-IO/qqq/blob/develop/CONTRIBUTING.md) +* Branches follow GitFlow: `feature/*` from `develop`, pull requests to `develop`, `release/*` for release candidates, `v*` tags for releases. +* Commits are signed and follow Conventional Commits. +* Build and test locally with `./mvnw verify` (Java 21). diff --git a/NOTICE b/NOTICE index 9612472..31460ab 100644 --- a/NOTICE +++ b/NOTICE @@ -1,5 +1,5 @@ -QBit Quick Search -Copyright 2024 Kingsrook, LLC +QBit CDN +Copyright 2026 Kingsrook, LLC This product includes software developed at Kingsrook, LLC (https://kingsrook.com/). diff --git a/README.md b/README.md index 270c755..5381034 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,12 @@ CloudFront credentials: `_ACCESS_KEY_ID` / `_SECRET_ACCESS Drift: the OpenTofu `expected_config` JSON in `CDN_EXPECTED_CONFIG` (or the variable named by the provider setting `expectedConfigEnv`). +## Build + ```sh ./mvnw verify # tests, coverage gate, checkstyle ``` + +## License + +Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..089e0f4 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,4 @@ +# Security Policy + + * See Project [Security Policy](https://github.com/QRun-IO/qqq/blob/develop/SECURITY.md) + * Report a vulnerability privately through this repository's **Security** tab ("Report a vulnerability"). diff --git a/docs/DESIGN.md b/docs/DESIGN.md new file mode 100644 index 0000000..3eb5bb5 --- /dev/null +++ b/docs/DESIGN.md @@ -0,0 +1,3 @@ +# QBit CDN: design + +The design for this qbit is tracked in [QRun-IO/qqq#1084](https://github.com/QRun-IO/qqq/pull/1084) (`docs/specs/2026-10-12-qbit-cdn-design.md`). This repository implements it; the implementation is in progress. diff --git a/mvnw b/mvnw old mode 100644 new mode 100755