aggify 0.3.8__tar.gz → 1.0.0__tar.gz

aggify-1.0.0/.gitignore

@@ -0,0 +1,314 @@
+### PyCharm ###
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+.idea/*
+.vscode
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### PyCharm Patch ###
+# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721
+
+# *.iml
+# modules.xml
+# .idea/misc.xml
+# *.ipr
+
+# Sonarlint plugin
+# https://plugins.jetbrains.com/plugin/7973-sonarlint
+.idea/**/sonarlint/
+
+# SonarQube Plugin
+# https://plugins.jetbrains.com/plugin/7238-sonarqube-community-plugin
+.idea/**/sonarIssues.xml
+
+# Markdown Navigator plugin
+# https://plugins.jetbrains.com/plugin/7896-markdown-navigator-enhanced
+.idea/**/markdown-navigator.xml
+.idea/**/markdown-navigator-enh.xml
+.idea/**/markdown-navigator/
+
+# Cache file creation bug
+# See https://youtrack.jetbrains.com/issue/JBR-2257
+.idea/$CACHE_FILE$
+
+# CodeStream plugin
+# https://plugins.jetbrains.com/plugin/12206-codestream
+.idea/codestream.xml
+
+# Azure Toolkit for IntelliJ plugin
+# https://plugins.jetbrains.com/plugin/8053-azure-toolkit-for-intellij
+.idea/**/azureSettings.xml
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
+test.py
+models.py
+# local virtualenvs / tooling
+.venv*/
+.hypothesis/
+
+# test models are source code
+!tests/models.py
+!docs/examples/shop_models.py

aggify-1.0.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: aggify
+Version: 1.0.0
+Summary: Async-first MongoDB ODM with a Django-style API: QuerySets, aggregation pipelines, FastAPI/gRPC/Django integrations.
+Project-URL: Homepage, https://github.com/Aggify/aggify
+Project-URL: Documentation, https://aggify.github.io/aggify
+Project-URL: Issues, https://github.com/Aggify/aggify/issues
+Author-email: "SeYeD.Dev" <me@seyed.dev>
+License: MIT License
+        
+        Copyright (c) 2023 SeYeD
+        
+        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.
+License-File: LICENSE
+Keywords: aggregation,async,django,fastapi,mongodb,odm,orm,pymongo
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pymongo<5,>=4.13
+Provides-Extra: all
+Requires-Dist: django>=4.2; extra == 'all'
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: grpcio>=1.60; extra == 'all'
+Requires-Dist: protobuf>=4.25; extra == 'all'
+Requires-Dist: pydantic>=2.5; extra == 'all'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Requires-Dist: pydantic>=2.5; extra == 'fastapi'
+Provides-Extra: grpc
+Requires-Dist: grpcio>=1.60; extra == 'grpc'
+Requires-Dist: protobuf>=4.25; extra == 'grpc'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.5; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://i.imgur.com/BBp9vUQ.png" alt="Aggify">
+</p>
+<p align="center">
+    <em>Async-first MongoDB ODM with a Django-style API - for Django, FastAPI, gRPC and plain Python</em>
+</p>
+
+[![Package version](https://img.shields.io/pypi/v/aggify?color=%2334D058&label=pypi%20package)](https://pypi.org/project/aggify)
+[![Downloads](https://img.shields.io/pypi/dm/aggify)](https://pypi.org/project/aggify)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/aggify.svg?color=%2334D058)](https://pypi.org/project/aggify)
+[![Coverage](https://img.shields.io/codecov/c/github/Aggify/aggify)](https://app.codecov.io/gh/Aggify/aggify)
+[![License](https://img.shields.io/github/license/Aggify/aggify.svg)](https://github.com/Aggify/aggify/blob/main/LICENSE)
+[![Telegram](https://img.shields.io/badge/-telegram-red?color=white&logo=telegram&logoColor=blue)](https://t.me/Aggify)
+
+**Aggify 1.0** is a complete rewrite: no MongoEngine, native `async`/`await` on pymongo's `AsyncMongoClient`, an API
+you already know from the Django ORM, and aggregation pipelines that fit on one line.
+
+```python
+import aggify
+from aggify import Document, StringField, DecimalField, ReferenceField, Sum, Count
+
+aggify.connect("mongodb://localhost:27017/shop")
+
+class Customer(Document):
+    name = StringField(required=True)
+    country = StringField(max_length=2)
+
+class Order(Document):
+    customer = ReferenceField(Customer)
+    status = StringField(choices=["new", "paid"], default="new")
+    total = DecimalField()
+
+best = await (
+    Order.objects.filter(status="paid", customer__country="DE")      # $lookup + $unwind + $match
+    .values("customer__name")
+    .annotate(revenue=Sum("total"), orders=Count())                  # $group
+    .filter(orders__gte=3)                                           # HAVING
+    .order_by("-revenue")[:10]                                       # $sort + $limit
+    .alist()
+)
+```
+
+## Highlights
+
+* **Sync *and* async** - every I/O method has an `a`-twin (`aget`, `alist`, `asave`, `acount`, `aupdate`, ...);
+  one async client per event loop, so it is safe in FastAPI, `grpc.aio`, Django's `async_to_sync` and pytest-asyncio.
+* **Django-style** - `Model.objects`, `Q`, `F`, `annotate`, `aggregate`, `values`, `select_related`, `get_or_create`,
+  signals, managers, `DoesNotExist`, pagination-ready querysets.
+* **Complex queries, short** - automatic joins (`owner__country="DE"`), `values().annotate()` grouping, conditional
+  aggregates (`Sum("x", filter=Q(...))`), window functions, `$facet`, `$bucket`, `$graphLookup`, sub-pipeline
+  `$lookup`, array operators, atomic expression updates. See the [cookbook](docs/cookbook.md).
+* **Framework-agnostic integrations** - `pip install "aggify[fastapi|grpc|django|pydantic]"`. Pydantic schemas from
+  documents, FastAPI lifespan/errors/pagination, gRPC status mapping, Django app/forms/shortcuts/middleware, and an
+  `ObjectIdField` to link Django ORM models to Mongo documents.
+* **Secure by default** - typed fields stop operator injection (`{"$ne": ""}`), regex lookups are escaped,
+  server-side JavaScript is blocked, field names validated, strict constructors, resource limits, masked credentials.
+* **Efficient** - `save()` sends only changed fields, optional optimistic locking, `only()/defer()/values()`,
+  streaming iterators, bulk operations.
+* **Well tested** - 470+ tests: unit, integration against a real replica set, differential property tests
+  (random `Q` trees vs. a Python reference), FastAPI/gRPC/Django end-to-end tests, Python 3.9-3.13.
+
+## Install
+
+```bash
+pip install aggify                       # core (pymongo >= 4.13)
+pip install "aggify[fastapi]"            # + pydantic / fastapi helpers
+pip install "aggify[django]" "aggify[grpc]" "aggify[all]"
+```
+
+## A tour
+
+```python
+# models: typed fields, embedded documents, references, indexes
+class Account(Document):
+    username = StringField(required=True, unique=True)
+    tags = ListField(StringField())
+    address = EmbeddedField(Address)
+    created_at = DateTimeField(auto_now_add=True)
+    class Meta:
+        ordering = ["username"]
+        indexes = [Index("tags")]
+
+# CRUD - only changed fields are written
+acc = await Account.objects.acreate(username="ali", tags=["vip"])
+acc.address = Address(city="Tehran")
+await acc.asave()                               # {"$set": {"address": {...}}}
+
+# querying
+Account.objects.filter(Q(tags="vip") | Q(address__city__istartswith="te"), ~Q(banned=True))
+Account.objects.filter(age__gt=F("score") * 10).only("username")[:20]
+
+# atomic updates, including server-side expressions
+Account.objects.filter(pk=acc.pk).update(inc__logins=1, push__tags="beta")
+Product.objects.update(price=Round(F("price") * Value(1.1), 2))
+
+# transactions (replica set)
+async with aggify.atransaction():
+    await Order.objects.acreate(...)
+    await Product.objects.filter(pk=pid).aupdate(inc__stock=-1)
+
+# the compiled query is always inspectable
+Account.objects.filter(address__city="Tehran").query
+```
+
+Need a stage a queryset does not have? The immutable pipeline builder is one call away:
+
+```python
+from aggify import Aggify
+Aggify(Order).filter(status="paid").facet(
+    by_country=Aggify(Order).group("customer__country", n=Count()),
+    page=[{"$limit": 20}],
+).execute()
+```
+
+## Documentation
+
+Full documentation lives in [`docs/`](docs/index.md) (build with `make docs`):
+[quickstart](docs/quickstart.md) - [models](docs/models.md) - [querying](docs/querying.md) -
+[pipelines](docs/aggregation.md) - [cookbook](docs/cookbook.md) - [security](docs/security.md) -
+[testing](docs/testing.md) - [Django](docs/integrations/django.md) - [FastAPI](docs/integrations/fastapi.md) -
+[gRPC](docs/integrations/grpc.md) - [MongoEngine migration](docs/migration/mongoengine.md) -
+[upgrading from 0.x](docs/migration/aggify-0.md) - [فارسی](docs/fa.md).
+
+## Development
+
+```bash
+make install && make mongo && make test      # needs Docker for the throw-away MongoDB replica set
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).

aggify-1.0.0/README.md

@@ -0,0 +1,130 @@
+<p align="center">
+  <img src="https://i.imgur.com/BBp9vUQ.png" alt="Aggify">
+</p>
+<p align="center">
+    <em>Async-first MongoDB ODM with a Django-style API - for Django, FastAPI, gRPC and plain Python</em>
+</p>
+
+[![Package version](https://img.shields.io/pypi/v/aggify?color=%2334D058&label=pypi%20package)](https://pypi.org/project/aggify)
+[![Downloads](https://img.shields.io/pypi/dm/aggify)](https://pypi.org/project/aggify)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/aggify.svg?color=%2334D058)](https://pypi.org/project/aggify)
+[![Coverage](https://img.shields.io/codecov/c/github/Aggify/aggify)](https://app.codecov.io/gh/Aggify/aggify)
+[![License](https://img.shields.io/github/license/Aggify/aggify.svg)](https://github.com/Aggify/aggify/blob/main/LICENSE)
+[![Telegram](https://img.shields.io/badge/-telegram-red?color=white&logo=telegram&logoColor=blue)](https://t.me/Aggify)
+
+**Aggify 1.0** is a complete rewrite: no MongoEngine, native `async`/`await` on pymongo's `AsyncMongoClient`, an API
+you already know from the Django ORM, and aggregation pipelines that fit on one line.
+
+```python
+import aggify
+from aggify import Document, StringField, DecimalField, ReferenceField, Sum, Count
+
+aggify.connect("mongodb://localhost:27017/shop")
+
+class Customer(Document):
+    name = StringField(required=True)
+    country = StringField(max_length=2)
+
+class Order(Document):
+    customer = ReferenceField(Customer)
+    status = StringField(choices=["new", "paid"], default="new")
+    total = DecimalField()
+
+best = await (
+    Order.objects.filter(status="paid", customer__country="DE")      # $lookup + $unwind + $match
+    .values("customer__name")
+    .annotate(revenue=Sum("total"), orders=Count())                  # $group
+    .filter(orders__gte=3)                                           # HAVING
+    .order_by("-revenue")[:10]                                       # $sort + $limit
+    .alist()
+)
+```
+
+## Highlights
+
+* **Sync *and* async** - every I/O method has an `a`-twin (`aget`, `alist`, `asave`, `acount`, `aupdate`, ...);
+  one async client per event loop, so it is safe in FastAPI, `grpc.aio`, Django's `async_to_sync` and pytest-asyncio.
+* **Django-style** - `Model.objects`, `Q`, `F`, `annotate`, `aggregate`, `values`, `select_related`, `get_or_create`,
+  signals, managers, `DoesNotExist`, pagination-ready querysets.
+* **Complex queries, short** - automatic joins (`owner__country="DE"`), `values().annotate()` grouping, conditional
+  aggregates (`Sum("x", filter=Q(...))`), window functions, `$facet`, `$bucket`, `$graphLookup`, sub-pipeline
+  `$lookup`, array operators, atomic expression updates. See the [cookbook](docs/cookbook.md).
+* **Framework-agnostic integrations** - `pip install "aggify[fastapi|grpc|django|pydantic]"`. Pydantic schemas from
+  documents, FastAPI lifespan/errors/pagination, gRPC status mapping, Django app/forms/shortcuts/middleware, and an
+  `ObjectIdField` to link Django ORM models to Mongo documents.
+* **Secure by default** - typed fields stop operator injection (`{"$ne": ""}`), regex lookups are escaped,
+  server-side JavaScript is blocked, field names validated, strict constructors, resource limits, masked credentials.
+* **Efficient** - `save()` sends only changed fields, optional optimistic locking, `only()/defer()/values()`,
+  streaming iterators, bulk operations.
+* **Well tested** - 470+ tests: unit, integration against a real replica set, differential property tests
+  (random `Q` trees vs. a Python reference), FastAPI/gRPC/Django end-to-end tests, Python 3.9-3.13.
+
+## Install
+
+```bash
+pip install aggify                       # core (pymongo >= 4.13)
+pip install "aggify[fastapi]"            # + pydantic / fastapi helpers
+pip install "aggify[django]" "aggify[grpc]" "aggify[all]"
+```
+
+## A tour
+
+```python
+# models: typed fields, embedded documents, references, indexes
+class Account(Document):
+    username = StringField(required=True, unique=True)
+    tags = ListField(StringField())
+    address = EmbeddedField(Address)
+    created_at = DateTimeField(auto_now_add=True)
+    class Meta:
+        ordering = ["username"]
+        indexes = [Index("tags")]
+
+# CRUD - only changed fields are written
+acc = await Account.objects.acreate(username="ali", tags=["vip"])
+acc.address = Address(city="Tehran")
+await acc.asave()                               # {"$set": {"address": {...}}}
+
+# querying
+Account.objects.filter(Q(tags="vip") | Q(address__city__istartswith="te"), ~Q(banned=True))
+Account.objects.filter(age__gt=F("score") * 10).only("username")[:20]
+
+# atomic updates, including server-side expressions
+Account.objects.filter(pk=acc.pk).update(inc__logins=1, push__tags="beta")
+Product.objects.update(price=Round(F("price") * Value(1.1), 2))
+
+# transactions (replica set)
+async with aggify.atransaction():
+    await Order.objects.acreate(...)
+    await Product.objects.filter(pk=pid).aupdate(inc__stock=-1)
+
+# the compiled query is always inspectable
+Account.objects.filter(address__city="Tehran").query
+```
+
+Need a stage a queryset does not have? The immutable pipeline builder is one call away:
+
+```python
+from aggify import Aggify
+Aggify(Order).filter(status="paid").facet(
+    by_country=Aggify(Order).group("customer__country", n=Count()),
+    page=[{"$limit": 20}],
+).execute()
+```
+
+## Documentation
+
+Full documentation lives in [`docs/`](docs/index.md) (build with `make docs`):
+[quickstart](docs/quickstart.md) - [models](docs/models.md) - [querying](docs/querying.md) -
+[pipelines](docs/aggregation.md) - [cookbook](docs/cookbook.md) - [security](docs/security.md) -
+[testing](docs/testing.md) - [Django](docs/integrations/django.md) - [FastAPI](docs/integrations/fastapi.md) -
+[gRPC](docs/integrations/grpc.md) - [MongoEngine migration](docs/migration/mongoengine.md) -
+[upgrading from 0.x](docs/migration/aggify-0.md) - [فارسی](docs/fa.md).
+
+## Development
+
+```bash
+make install && make mongo && make test      # needs Docker for the throw-away MongoDB replica set
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).

aggify-1.0.0/SECURITY.md

@@ -0,0 +1,48 @@
+# Security Policy
+
+## Reporting a Security Issue
+
+At Aggify, we take security seriously. We appreciate your help in identifying and addressing security issues. To report a security issue, please follow the guidelines below:
+
+**DO NOT** create a public GitHub issue for security-related problems.
+
+Instead, please email us directly at [support@aggify.org](mailto:support@aggify.org) with the following information:
+
+1. A detailed description of the security issue, including any potential impact.
+2. Steps to reproduce the issue or a proof-of-concept if applicable.
+3. Any additional details that can help us understand and address the problem.
+
+We will respond to your report as soon as possible and, if necessary, provide a timeline for a fix. We greatly appreciate responsible disclosure.
+
+## Supported Versions
+
+Aggify's security policy applies to the most recent stable release and the previous release. We encourage users to always keep their installations up to date with the latest version.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| 0.x     | :x: (superseded by the 1.0 rewrite - please upgrade) |
+
+## Security Updates
+
+We are committed to addressing security issues promptly. In the event of a confirmed security vulnerability, we will:
+
+- Acknowledge receipt of the report within 48 hours.
+- Investigate and verify the reported issue.
+- Develop and test a fix.
+- Release a security update.
+- Credit the individual or organization that reported the vulnerability.
+
+## Contact
+
+If you have any questions or concerns regarding the security of Aggify, please contact us at [support@aggify.org](mailto:support@aggify.org). Our team will be happy to assist you.
+
+Thank you for helping us make Aggify more secure.
+
+
+## Threat model and built-in protections
+
+Aggify's protections (operator-injection prevention, regex escaping, JavaScript blocking, validated field names, resource
+limits, credential masking) and what remains the application's responsibility are documented in
+[docs/security.md](docs/security.md). Reports that bypass any of them - for example a value that reaches a query with
+a `$` operator without going through `Raw()` - are treated as vulnerabilities.