cloudoll 4.2.1__tar.gz → 4.4.0__tar.gz

cloudoll-4.4.0/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Changelog
+
+简体中文见 [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md)。
+
+## 4.4.0
+
+Defect-fix release; backward compatible. Python 3.9+ remains supported.
+
+### Database
+
+- `for_update()` row locks now require your own transaction. Outside one, the lock
+  was released by the commit that `for_update()` issued itself and protected
+  nothing; such a call now raises instead of silently doing nothing.
+- A transaction cancelled or timed out while waiting for a connection gives that
+  connection back to the pool, so long-running services stop losing connections.
+- Model fields are hashable again: columns can go into sets and serve as dict
+  keys (deduplicating columns, excluding groups of fields).
+- `SUM(DISTINCT column)` and similar aggregate deduplication now happens inside
+  the aggregate, so values are deduplicated before being combined, and a literal
+  inside an aggregate is no longer bound twice.
+- URL query parameters in an AWS datasource string are no longer handed to the
+  driver as unknown connection options.
+
+### Web and templates
+
+- A response that has already started streaming keeps its body when an error
+  occurs; the JSON error handler no longer rewrites it. Streaming and SSE
+  endpoints stay intact.
+- Page responses no longer repeat `charset` in `Content-Type`.
+- `session` options (`key`, `max_age`, `httponly`, `secure`, `domain`, `path`,
+  `samesite`) apply to encrypted cookie, Redis and Memcached storage alike.
+- `render_view()` keywords are `Response` options only, and the template context
+  is the positional mapping. A stray keyword now raises `TypeError` instead of
+  being silently merged into the context.
+- Development servers bind to 127.0.0.1 by default and no longer occupy
+  `port + 1`.
+- `server.ignore_dirs` is honoured for directories such as `logs`, so writing logs
+  no longer triggers a reload.
+- The scaffolded authorization middleware now matches its documentation: it is an
+  async decorator, lets static paths through, and lets downstream failures reach
+  the error layer instead of being flattened into a 500 that echoes the exception
+  text.
+
+### Command line and new projects
+
+- `cloudoll create` no longer copies `__pycache__` and `.pyc` files into the new
+  project.
+- The last component of a project name must be letters, digits, underscore, dot
+  or dash; names with spaces or shell characters are refused, as is an existing
+  target directory.
+- A failed creation exits with a non-zero status and removes the half-written
+  project instead of leaving it behind.
+- New projects write independent JWT and session keys to `.env`, which
+  `.gitignore` keeps out of version control. Local starts no longer warn about a
+  random process-local session key, and logins survive a restart or an added
+  worker.
+
+### Mail and utilities
+
+- Building a `cloudoll.mail.smtp.Client` no longer reaches the network, and one
+  client stays usable across sends and server idle timeouts: each `send()` opens
+  its own connection, carries one copy of the body, and closes the connection even
+  when the send fails.
+- Missing credentials and an empty recipient address now raise a readable error
+  before anything is sent.
+- `cloudoll.utils` - reversible encryption, keyed digests, random strings and the
+  distributed ID generator - is now official API with a
+  [utilities](https://cloudoll.chuchur.com/utils) page and regression tests. None
+  of them is a password hash; store user passwords with bcrypt or argon2.
+- New [mail](https://cloudoll.chuchur.com/mail) page documents sending limits
+  (SMTPS 465 only, no STARTTLS, no retry or queue). The dead POP3 draft under
+  `cloudoll/mail` is gone - Cloudoll does not receive mail.
+
+### Upgrade notes
+
+- `for_update()` outside a transaction and unexpected `render_view()` keywords now
+  raise rather than misbehaving quietly; audit those two call shapes before
+  upgrading.
+- `cloudoll create` rejects names it used to accept, such as `my shop`, because
+  they reached a shell unsafely.
+- Projects created before this release keep an old `config/conf.local.yaml`
+  without a session key; add `session.secret_key` (or set
+  `CLOUDOLL_SESSION_SECRET`) so sessions survive restarts and multiple workers.
+- Existing `.env` files need the new `CLOUDOLL_SESSION_SECRET` entry; `.env` has
+  always been ignored by the project's `.gitignore`.
+
+### Documentation
+
+- JWT middleware examples use `web.RequestKey` instead of a plain string key, so
+  aiohttp stops warning about it.
+- The quick start and session pages describe how a new project injects its keys.
+
+## 4.3.0
+
+### ORM queries and writes
+
+- Add explicit LEFT/INNER/RIGHT JOIN kinds, query-level DISTINCT, `one_dict()`
+  for projected/aggregate rows, and non-consuming `exists()` checks.
+- Add parameterized scalar/IN and EXISTS/NOT EXISTS subqueries with snapshot
+  semantics and datasource/dialect compatibility checks.
+- Add read-only table aliases for self-joins, non-recursive CTEs, and
+  UNION/UNION ALL with branch-local and outer pagination semantics.
+- Add atomic expression-valued updates and transaction-owned `for_update()`
+  row locks, including mutually exclusive NOWAIT and SKIP LOCKED options.
+- Add single-statement `upsert()` with explicit update fields; PostgreSQL
+  supports conflict targets, while MySQL explicitly rejects that option.
+- Export `Relation` and `Subquery` types. Reject writes against aliases,
+  CTE/UNION sources and joined queries rather than silently ignoring sources.
+
+### Documentation and verification
+
+- Expand grouping/HAVING, aggregates, default datasource usage and query
+  result contracts. Normal application CRUD defaults to entity APIs without
+  unnecessary `.use(db)` or handwritten SQL.
+- Update bundled AI guidance and version-matched examples, including locking,
+  unique constraints, snapshots and unsupported advanced combinations.
+- Add MySQL 8.4/PostgreSQL 16 integration coverage for query sources, upserts,
+  concurrency, rollback and row-lock contention. Aurora remains unverified.
+
+## 4.2.1
+
+- Correct the AI initialization regression test to compare the original bytes
+  rather than assume LF newlines on Windows. Keep preservation and idempotence
+  assertions enabled on every platform.
+- Normalize the generated full documentation's trailing newline.
+- Include all 4.2.0 features. The 4.2.0 tag was blocked by Windows CI and was
+  not published to PyPI; 4.2.1 is the replacement release.
+
+## 4.2.0
+
+Backward-compatible AI-assisted development release. Python 3.9+ remains supported.
+
+- Add offline `cloudoll ai list`, `read`, and `search` commands for bundled official
+  documentation, with source URLs, version metadata and content integrity checks.
+- Add `cloudoll ai init` for existing projects. New scaffolds automatically include
+  an AGENTS.md entry and a project-local Cloudoll skill covering documented project
+  structure, validation, ORM, resource lifecycle, security and verification.
+- Preserve existing project instructions and refuse to overwrite customized skills
+  or write through symbolic links. Initialization is repeatable.
+- Add documentation synchronization tooling and website LLM discovery assets.
+  Test both instruction initialization and AI resources in the built wheel.
+
+## 4.1.0
+
+Backward-compatible feature release. Pydantic 2 (`>=2.0,<3`) is now a core
+runtime dependency. Existing handlers and explicit ORM engine bindings remain
+supported. Python 3.9+ remains supported by the CI matrix.
+
+- Correct lifecycle callback and JWT payload type declarations for strict
+  checking with current dependency annotations.
+- Include HTTP method and actual request path in exception logs; emit 4xx access
+  logs at WARNING and 5xx at ERROR so failed requests remain visible above INFO.
+
+- Add Pydantic 2 request validation with typed `Body`, `Query`, `Form`, and
+  `Path` bindings, repeated collection parameters and structured HTTP 400 errors.
+  Preserve legacy request and streaming multipart handlers.
+
+- Add application-local named ORM datasources via `orm.default` and model
+  `__datasource__`, independent class-level queries, `Model.query()` and
+  `Model.transaction()`. Reuse existing task-owned engine transactions.
+- Add `datasource_context` for scoped standalone/test engine bindings. Keep
+  explicit `.use(engine)`, offline SQL compilation and bound records compatible.
+
+## 4.0.0
+
+This release contains breaking changes to configuration, security, ORM and the
+application lifecycle. Read the migration guide before upgrading.
+
+### Breaking changes and migration
+
+- Python 3.9+ is required; database/cache drivers are optional extras.
+- Configuration values no longer execute Python expressions. Supply literal
+  numeric values and inject required environment variables explicitly.
+- `Model.use()` returns an independent Query. Records use UNSET and dirty-field
+  snapshots; successful outer commits update the saved baseline. Database errors
+  propagate instead of appearing as empty results.
+- PostgreSQL ORM inserts use RETURNING. Raw inserts without RETURNING and batch
+  inserts do not manufacture a primary key.
+- Sessions require a private, stable key for multi-worker/restart persistence;
+  discard cookies created with old publicly derivable keys.
+- Middleware uses the direct async decorator contract. Application creation is
+  instance-local and may only be performed once per instance.
+- CLI service identity includes process creation time and command line. Unknown
+  legacy PID identities are not killed automatically; stop old services safely
+  before upgrading. Production mode remains foreground, not a process supervisor.
+
+### ORM and developer experience
+
+- Added native MySQL/PostgreSQL transactions, nested savepoints, scoped streaming,
+  generic Query/Field typing and dialect-specific schema generation.
+- Added opt-in SQL/parameter echo, connection/query/cleanup timeouts, and safe
+  cancellation. Writes and uncertain commits are never automatically replayed.
+- Added isolated route/module discovery and explicit application components.
+- Development children and reloads create a fresh Application at the explicit
+  project root instead of inheriting a parent's cached app/context through fork.
+- Scaffold dependencies now target Cloudoll 4.0.0; scaffold business code remains
+  illustrative, not a complete application authorization system.
+
+### Core production hardening
+
+- Explicitly selected missing configuration files now raise `FileNotFoundError`.
+  Use `Application.create(env=None)` or `config={}` for intentional no-config mode.
+- Library-owned configuration types/ranges are validated before startup and after
+  `on_create`. Custom business/plugin keys remain supported.
+- JWT verification requires `exp` by default and supports issuer, audience,
+  leeway and required claims. Invalid tokens return `None`; configuration errors
+  raise. Explicit `require=()` is the legacy-token escape hatch.
+- Native pool close and application resource cleanup have finite deadlines.
+- Added JSON logging, structured-data masking, string-redaction extension,
+  trace correlation and value-free HTTP/native query observation events.
+- Added native deadlock/commit-cancellation regression tests and dependency audit CI.
+
+### Migration
+
+See [reliability](docs/reliability.md) for the existing transaction, savepoint,
+UNSET/dirty-field, CLI/PID, SQL echo and request parsing changes. See
+[production contracts](docs/production.md) for the new configuration and APIs.
+
+Aurora transactions and connection reuse are implemented but remain untested.
+Native driver validation must not be presented as Aurora failover validation.

{cloudoll-4.2.1 → cloudoll-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudoll
-Version: 4.2.1
+Version: 4.4.0
 Summary: Assist in quickly creating distributable microservices based on aiohttp, with a focus on simplicity and ease of use.
 Author-email: Qiu <smallerqiu@gmail.com>
 License-Expression: MIT
@@ -54,7 +54,7 @@ Dynamic: license-file
 
 English | [简体中文](README.zh-CN.md)
 
-Cloudoll 4.2.1 is an aiohttp-based Python library for routing, middleware,
+Cloudoll 4.4.0 is an aiohttp-based Python library for routing, middleware,
 templates, sessions, JWT, database access and application scaffolding.
 
 ## AI-assisted development
@@ -71,8 +71,8 @@ does not have `cloudoll ai --help`, consult its matching README and source first
 Python 3.9+ is required. Install only the optional drivers you use:
 
 ```sh
-python -m pip install 'cloudoll==4.2.1'
-python -m pip install 'cloudoll[mysql,postgres,cache]==4.2.1'
+python -m pip install 'cloudoll==4.4.0'
+python -m pip install 'cloudoll[mysql,postgres,cache]==4.4.0'
 ```
 
 The AWS extra requires Python 3.10+. Aurora remains untested; see
@@ -87,7 +87,8 @@ python -m pip install -r requirements.txt
 cloudoll start -n myapp
 ```
 
-The generated project targets 4.2.1 and receives a random JWT secret. Controllers
+The generated project targets 4.4.0 and receives random JWT and session secrets
+in `.env`. Controllers
 and authentication middleware are examples: replace demo credentials and supply
 your own authorization and upload policies before deployment.
 
@@ -172,8 +173,8 @@ python -m ruff check cloudoll tests
 python -m mypy
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.2.1-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.2.1-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.4.0-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.4.0-py3-none-any.whl
 ```
 
 Native integration tests require explicitly configured disposable databases.

{cloudoll-4.2.1 → cloudoll-4.4.0}/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-Cloudoll 4.2.1 is an aiohttp-based Python library for routing, middleware,
+Cloudoll 4.4.0 is an aiohttp-based Python library for routing, middleware,
 templates, sessions, JWT, database access and application scaffolding.
 
 ## AI-assisted development
@@ -19,8 +19,8 @@ does not have `cloudoll ai --help`, consult its matching README and source first
 Python 3.9+ is required. Install only the optional drivers you use:
 
 ```sh
-python -m pip install 'cloudoll==4.2.1'
-python -m pip install 'cloudoll[mysql,postgres,cache]==4.2.1'
+python -m pip install 'cloudoll==4.4.0'
+python -m pip install 'cloudoll[mysql,postgres,cache]==4.4.0'
 ```
 
 The AWS extra requires Python 3.10+. Aurora remains untested; see
@@ -35,7 +35,8 @@ python -m pip install -r requirements.txt
 cloudoll start -n myapp
 ```
 
-The generated project targets 4.2.1 and receives a random JWT secret. Controllers
+The generated project targets 4.4.0 and receives random JWT and session secrets
+in `.env`. Controllers
 and authentication middleware are examples: replace demo credentials and supply
 your own authorization and upload policies before deployment.
 
@@ -120,8 +121,8 @@ python -m ruff check cloudoll tests
 python -m mypy
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.2.1-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.2.1-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.4.0-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.4.0-py3-none-any.whl
 ```
 
 Native integration tests require explicitly configured disposable databases.

{cloudoll-4.2.1 → cloudoll-4.4.0}/README.zh-CN.md

@@ -2,11 +2,11 @@
 
 [English](README.md) | 简体中文
 
-生产配置、资源关闭期限、JWT 验证、JSON 日志与监控接入见 [生产运行契约](docs/production.md)；版本兼容及发布检查见 [维护政策](docs/maintenance.md)，安全问题报告见 [SECURITY.md](SECURITY.md)。
+生产配置、资源关闭期限、JWT 验证、JSON 日志与监控接入见 [生产运行契约](docs/production.md)；版本兼容及发布检查见 [维护政策](docs/maintenance.md)；各版本变化见 [更新日志](CHANGELOG.zh-CN.md)，安全问题报告见 [SECURITY.md](SECURITY.md)。
 
 Cloudoll 是一个基于 aiohttp 的 Python Web 开发库，提供路由自动注册、中间件、模板渲染、会话管理、JWT、数据库访问及命令行脚手架，帮助快速构建 Web 应用和微服务。
 
-本文适用于 Cloudoll 4.2.1。从 3.x 升级前请阅读下方迁移说明。
+本文适用于 Cloudoll 4.4.0。从 3.x 升级前请阅读下方迁移说明。
 
 ## AI 辅助开发
 
@@ -25,10 +25,10 @@ Cloudoll 是一个基于 aiohttp 的 Python Web 开发库，提供路由自动
 
 ## 安装
 
-安装 4.2.1：
+安装 4.4.0：
 
 ```sh
-python -m pip install 'cloudoll==4.2.1'
+python -m pip install 'cloudoll==4.4.0'
 ```
 
 在当前仓库目录安装源码：
@@ -41,16 +41,16 @@ python -m pip install -e .
 
 ```sh
 # MySQL
-python -m pip install 'cloudoll[mysql]==4.2.1'
+python -m pip install 'cloudoll[mysql]==4.4.0'
 
 # PostgreSQL
-python -m pip install 'cloudoll[postgres]==4.2.1'
+python -m pip install 'cloudoll[postgres]==4.4.0'
 
 # AWS 数据库驱动
-python -m pip install 'cloudoll[aws]==4.2.1'
+python -m pip install 'cloudoll[aws]==4.4.0'
 
 # Redis / Memcached 会话或 Redis 数据库
-python -m pip install 'cloudoll[cache]==4.2.1'
+python -m pip install 'cloudoll[cache]==4.4.0'
 ```
 
 源码开发时可用 `python -m pip install -e '.[mysql,postgres,cache,dev]'` 安装。
@@ -89,7 +89,7 @@ myapp/
 └── templates/
 ```
 
-脚手架中的鉴权中间件和登录接口用于演示。正式使用前，应替换示例账号、密码和业务鉴权逻辑。新建项目会获得独立的 JWT 密钥。
+脚手架中的鉴权中间件和登录接口用于演示。正式使用前，应替换示例账号、密码和业务鉴权逻辑。新建项目会在 `.env` 里获得相互独立的 JWT 与 Session 密钥。
 
 ### 手动创建应用
 
@@ -546,8 +546,8 @@ cloudoll restart -n myapp
 python -m pip install -e '.[mysql,postgres,cache,dev]'
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.2.1-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.2.1-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.4.0-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.4.0-py3-none-any.whl
 ```
 
 最后一条命令用于验证构建出的 wheel，版本号变化后请调整文件名。测试使用模拟数据库连接及本机 HTTP 服务；真实数据库连接和 AWS 故障切换需要单独的集成环境。

cloudoll-4.4.0/cloudoll/__init__.py

@@ -0,0 +1 @@
+__version__ = "4.4.0"

{cloudoll-4.2.1 → cloudoll-4.4.0}/cloudoll/ai/AGENTS.md

@@ -5,3 +5,7 @@ Before building or changing a Cloudoll application, read `.agents/skills/cloudol
 Official documentation is bundled with the installed library: `python -m cloudoll.cli ai list`, `ai read <topic>`, and `ai search <query>`. These commands work offline without MCP. Read `structure`, `config`, `router`, and `validation` before designing an application; read `database` before database work. Consult the installed source when resolving a signature discrepancy; report the discrepancy rather than inventing an API.
 
 Prefer the documented scaffold, auto-discovered controllers/middlewares, YAML configuration, framework-owned database lifecycle, typed request validation, and ORM for ordinary CRUD. Low-level alternatives require a task-specific reason. Never silently replace Cloudoll's architecture with patterns from another framework.
+
+Ordinary CRUD, joins, filters, aliases, counts and pagination use entity/Query APIs. With initialized application datasources and `orm.default`, omit `.use(db)` in routes and services; explicit binding is for intentional overrides or context-free scripts/tests. Before using raw SQL, verify and state the specific ORM capability gap, not merely that the query contains JOIN or COUNT.
+
+Grouping, HAVING and aggregate expressions are also supported. Consult the installed database topic for the full capability inventory; 4.3.0 additions must not be assumed available in an older installed release.

{cloudoll-4.2.1 → cloudoll-4.4.0}/cloudoll/ai/docs/ai.md

@@ -49,6 +49,8 @@ python -m cloudoll.cli ai search transaction
 .agents/skills/cloudoll/SKILL.md，再通过 cloudoll ai read 查阅相关文档。
 新项目遵循自动发现的 controllers/middlewares、YAML 配置、框架管理的
 数据库生命周期、类型化参数校验和 ORM。若需要偏离默认方案，先说明理由。
+普通 CRUD、联表、筛选、计数和分页用实体 API；配置 orm.default 后，
+应用代码默认省略 .use(db)。原始 SQL 须先确认并说明当前 ORM 的具体能力缺口。
 完成后说明查阅的主题、测试结果和未验证的部分。
 ```
 

{cloudoll-4.2.1 → cloudoll-4.4.0}/cloudoll/ai/docs/changelog.md

@@ -6,10 +6,74 @@ icon: logs
 
 # 更新日志
 
-按版本倒序记录 Cloudoll 的主要变化。当前使用方法请以本站 4.2.1 文档为准，历史功能不代表当前仍保留相同 API。
+按版本倒序记录 Cloudoll 的主要变化。当前使用方法请以本站 4.4.0 文档为准，历史功能不代表当前仍保留相同 API。
 
 历史版本日期为对应源码提交日期。各版本源码可通过表格中的链接查看。
 
+## 4.4.0
+
+缺陷修复版本，向后兼容；Python 3.9+ 仍然支持。
+
+### 数据库
+
+- `for_update()` 行锁必须在调用方自己的事务里使用。以前脱离事务的写法会临时开一个事务，锁随提交立刻释放，实际什么都没锁住；现在这样的调用直接报错。
+- 开启事务时获取连接超时或被取消，已借到的连接会归还连接池，服务跑久了不再慢慢耗光连接。
+- 模型字段恢复可哈希，可以放进 `set` 或作为字典键（列去重、批量排除字段）。
+- `SUM(DISTINCT column)` 等聚合去重编译到聚合函数内部，去重发生在求和之前；聚合里的字面量不再被重复绑定参数。
+- AWS 数据源串里的 URL 查询参数不再作为未知参数传给驱动。
+
+### Web 与模板
+
+- 已经开始输出的响应不再被 JSON 错误处理改写坏，流式与 SSE 接口出错时保留原响应。
+- 页面响应的 `Content-Type` 不再出现两个 `charset`。
+- `session` 的 `key`、`max_age`、`httponly`、`secure`、`domain`、`path`、`samesite` 在加密 Cookie、Redis、Memcached 三种存储下都生效。
+- `render_view()` 的关键字参数只归一处：模板上下文按位置传字典，关键字参数一律是 `Response` 选项，传错直接抛 `TypeError`，不再被当成上下文吞掉。
+- 默认监听 127.0.0.1，开发模式不再额外占用配置端口 +1。
+- `server.ignore_dirs` 对 `logs` 等目录生效，写日志不再触发热重载。
+- 脚手架的鉴权中间件示例与文档一致：async 装饰器写法，放行静态资源，不再把后续处理器的异常吞成带错误文本的 500。
+
+### 命令行与新建项目
+
+- `cloudoll create` 不再把 `__pycache__`、`.pyc` 复制进新项目。
+- 项目名最后一段只能是字母、数字、下划线、点、短横线；带空格或 shell 元字符的名字被拒绝，已存在的目标目录也会报错。
+- 创建失败时退出码非 0，并回收只写了一半的目录，不会留下半个项目。
+- 新项目在 `.env` 里同时生成 JWT 与 Session 两把独立密钥，配置读取环境变量，`.gitignore` 忽略 `.env`。本地启动不再出现“使用随机进程本地密钥”的告警，重启和多 worker 之间登录状态不再丢失。
+
+### 邮件与工具函数
+
+- 邮件客户端构造时不再立刻联网，发送过一次或服务器空闲断开后仍能继续使用：每次 `send()` 自建连接、只带一份正文，失败时也会关闭连接。
+- 缺少账号或授权码、收件人为空时立即给出可读错误，不再留给服务器报认证失败。
+- `cloudoll.utils` 的可逆加密、单向摘要、随机字符串、分布式 ID 成为正式 API，见[工具函数](/utils)。存用户密码请改用 bcrypt/argon2，这些工具都不是口令哈希。
+- 新增[发送邮件](/mail)页；`cloudoll/mail` 下从未生效的 POP3 草稿文件被移除，库本身不提供收信能力。
+
+### 升级提示
+
+- 在事务外调用 `for_update()`、给 `render_view()` 传多余关键字，以前是静默出错，现在会抛异常；升级前先检查这两类调用。
+- `cloudoll create` 开始拒绝带空格和 shell 元字符的项目名。
+- 老项目请自行补上 `session.secret_key` 或 `CLOUDOLL_SESSION_SECRET`，否则重启、多 worker 之间仍会丢登录状态。
+
+### 文档
+
+- JWT 中间件示例改用 `web.RequestKey`，避免 aiohttp 的字符串键告警。
+- [快速开始](/)与 [Cookie 与 Session](/session-cookie)说明新项目的密钥注入方式。
+
+## 4.3.0
+
+### ORM 查询与写入
+
+- JOIN 新增显式 LEFT/INNER/RIGHT 类型，默认保持 LEFT；增加查询级 `distinct()`、保留聚合与别名列的 `one_dict()`、不消费查询的 `exists()`。
+- 新增参数化 IN、标量、EXISTS/NOT EXISTS 子查询，创建时快照 SQL 与参数，并校验数据源和方言。
+- 新增 `Model.alias()` 表别名和自连接、非递归 CTE、UNION/UNION ALL；区分分支分页与合并结果分页，保留正确计数语义。
+- 新增表达式原子更新和 `for_update()` 行锁，支持 NOWAIT、SKIP LOCKED；事务由调用方管理，不自动重试。
+- 新增单条原子 `upsert()`，显式指定更新列；PostgreSQL 支持冲突目标，MySQL 明确拒绝不能实现的冲突目标选项。
+- 导出 `Relation`、`Subquery` 类型；明确拒绝别名、CTE、UNION 和 JOIN 查询的直接写入，避免静默忽略查询源。
+
+### 文档与验证
+
+- 补齐 GROUP BY、HAVING、聚合、返回类型和默认数据源示例；普通应用 CRUD 优先实体 API，不必重复 `.use(db)`。
+- 同步 AI 指引与随包文档，说明行锁、唯一约束、版本适用范围和高级查询限制。
+- 增加 MySQL 8.4 / PostgreSQL 16 真实数据库测试，覆盖并发 upsert、回滚、锁竞争、CTE 和 UNION。Aurora 仍未经过真实环境验证。
+
 ## 4.2.1
 
 - 修正 AI 初始化测试对 Windows CRLF 换行的错误假设，继续验证原有内容保留和重复初始化不变。
@@ -26,8 +90,6 @@ icon: logs
 
 ## 4.1.0
 
-本节对应 4.1.0 源码变更；实际发布状态以 PyPI 为准。
-
 - [默认数据源](/database#默认数据源与模型绑定)：orm.default、模型 __datasource__、独立类级查询、query() 与 transaction()，保留显式 use(engine)。
 - datasource_context 为独立任务和测试提供作用域绑定；事务复用现有引擎机制，应用与并发任务保持隔离。
 - [请求参数校验](/validation)：Pydantic 2 支持 Body、Query、Form、Path，重复数组参数和结构化 HTTP 400，兼容旧接口与流式上传。

{cloudoll-4.2.1 → cloudoll-4.4.0}/cloudoll/ai/docs/config.md

@@ -14,9 +14,21 @@ CLI 默认读取项目根目录的 `config/conf.local.yaml`。选择生产配置
 cloudoll start -n myapp -env prod -m production
 ```
 
-`-env prod` 选择文件，`-m production` 选择运行模式，两者不是同一个开关。通过 `--host` / `--port` 可覆盖监听地址；未传入时使用配置。入口参数 `-e app` 是模块名，不是 `app.py`。
+`-env prod` 选择文件，`-m production` 选择运行模式，两者不是同一个开关。通过 `--host` / `--port` 可覆盖监听地址；未传入时使用配置。配置也缺省时，监听地址为本机回环 `127.0.0.1`、端口 `9001`；需要对外提供服务时显式写入 `server.host: 0.0.0.0` 或使用 `--host 0.0.0.0`。开发模式只有工作进程监听业务端口，监督进程不占用其他端口。入口参数 `-e app` 是模块名，不是 `app.py`。
 
-配置必须是 YAML 映射；加载时使用安全 YAML 解析和严格环境变量展开。缺少环境变量会报错。Cloudoll 没有自动加载项目 `.env` 文件的逻辑，应由 shell、容器或进程管理器注入变量。
+配置必须是 YAML 映射；加载时使用安全 YAML 解析，并通过 EnvYAML 严格展开环境变量。默认情况下，缺少引用的环境变量会报错。
+
+### `.env` 文件
+
+EnvYAML 会自动读取当前工作目录下的 `.env`。从项目根目录启动时，可将配置中引用的变量放在根目录的 `.env` 中，也可以由 shell、容器或进程管理器注入。
+
+- 可通过进程环境变量 `ENV_FILE` 指定其他文件；从不同目录启动时，建议使用绝对路径。
+- 默认 `.env` 路径相对于当前工作目录，不是 YAML 所在目录；`get_config(..., root=...)` 只指定 YAML 配置的根目录，不改变 `.env` 的查找位置。
+- 当前 EnvYAML 实现中，文件中的变量会覆盖同名进程环境变量，再用于 YAML 占位符展开。生产环境应避免残留本地 `.env` 覆盖部署配置。
+- 文件变量仅进入 EnvYAML 配置，不会写入 `os.environ`；直接使用 `os.getenv()` 或 `os.environ` 的业务代码不能因此读到这些变量。
+- `-env prod` 选择 `config/conf.prod.yaml`，不会自动切换为 `.env.prod`；需要时通过 `ENV_FILE` 指定。
+
+不要提交包含密码或密钥的 `.env`；可提交仅包含变量名和占位值的 `.env.example`。
 
 显式指定的配置文件不存在会抛 FileNotFoundError，不再返回空配置继续启动。核心配置节、端口/请求大小、布尔开关、资源关闭期限和 JWT 策略会在应用创建时校验，on_create 修改后再次校验。业务自定义键仍可使用；数据库驱动参数由相应引擎校验。
 

{cloudoll-4.2.1 → cloudoll-4.4.0}/cloudoll/ai/docs/cookie-and-session.md

@@ -78,9 +78,14 @@ session:
   max_age: 86400
   httponly: true
   secure: false
+  domain: .example.com
+  path: /
+  samesite: Lax
 ```
 
-也可只在进程环境设置 CLOUDOLL_SESSION_SECRET。未配置时生成应用进程本地随机密钥，重启会使旧 Session 失效，多进程间也不能共享；生产必须使用一致的随机密钥。更换密钥会使原 Cookie 失效。
+`domain`、`path`、`samesite` 属于 Session Cookie 本身，Cookie、Redis、Memcached 三种存储都读取同一份配置；Redis 存储下不要把这三个键写进 `redis` 子配置。`samesite` 只接受 `Strict`、`Lax`、`None`；`None` 表示不下发该属性，使用浏览器默认策略。`path` 决定浏览器在哪些路径回传 Session Cookie，改成子路径后原路径下的请求将不再带会话。HTTPS 生产环境使用 `secure: true`，此时 `samesite: None` 还要求浏览器允许跨站发送，仅在确有跨站回调时使用。
+
+`cloudoll create` 生成的项目已在 `config/conf.local.yaml` 写好 `session.secret_key: $CLOUDOLL_SESSION_SECRET`，并把随机密钥连同 JWT 密钥一起写入项目根目录的 `.env`，开箱即用、重启不掉线；`.env` 已被 `.gitignore` 忽略，生产环境改用环境变量注入同名变量。也可只在进程环境设置 CLOUDOLL_SESSION_SECRET。两处都没有时框架生成应用进程本地随机密钥并记录一次告警，重启会使旧 Session 失效，多进程间也不能共享；生产必须使用一致的随机密钥。更换密钥会使原 Cookie 失效。
 
 Cookie 容量有限，不要保存大对象、密码或完整业务数据。客户端加密 Cookie 模式无法仅靠退出操作撤销其他地方留存的旧 Cookie；需要集中撤销时使用服务端存储及业务级会话控制。