lcl-fastapi 0.1.0__tar.gz

lcl_fastapi-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+venv/
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+pytest-cache-files-*/
+.mypy_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+reports/
+dist/
+build/
+run/
+logs/
+*.log
+.DS_Store

lcl_fastapi-0.1.0/AGENTS.md

@@ -0,0 +1,255 @@
+# lcl-fastapi project facts
+
+This repository implements the reviewed `lcl-fastapi spec.md`. Development discussions may be Chinese; public documentation and production docstrings are English.
+
+- Distribution: `lcl-fastapi`; import package: `lcl_fastapi`; production root: `src/lcl_fastapi`.
+- License: MIT. Python metadata requires >=3.14; the initial target validation matrix is CPython 3.14 on Windows and Linux. Future versions are not claimed as tested.
+- Runtime dependencies: lclang==1.0.10, FastAPI >=0.141,<0.142, Uvicorn >=0.52,<0.53, psutil >=7.2,<8, Winloop ==0.6.3 on Windows only, and Gunicorn >=26,<27 on Linux only. Use lclang.cli; argparse, Click and Typer are not allowed.
+- Configuration comes from .lclcfg. The reviewed specification governs actual key names and semantics, including the complete public origin. Use lclang's formal logger settings and Snowflake implementation.
+- Default branch: main; persistent publication branch: release; feature prefix: codex/. The user has authorized reviewing and squash-merging the implementation PR, then publishing the first 0.1.0 release through CI to PyPI and GitHub. Keep main and release; clean up the completed feature branch only after verified publication.
+- This was an empty GitHub repository. An empty main bootstrap commit may establish a PR base. All product changes belong in the implementation PR.
+- Version authority: pyproject.toml; any runtime version uses installed distribution metadata.
+- Authoritative quality command: `venv/Scripts/python.exe -m scripts.quality` on Windows and `venv/bin/python -m scripts.quality` on Linux. The quality entry point, structural production policy, architecture, documentation/link, artifact-integrity checks, and cross-platform coverage CI are implemented. Semantic policy compliance requires review. Full compliance is established by the latest PR head's Windows/Linux jobs and strict aggregate coverage report, not by the presence of configured checks.
+- Expected documentation entries: README.md, docs/development-plan.md, reference and guide pages under docs/. Examples are independent downstream projects and must not enter the wheel.
+- Platform-specific real-process tests run on their respective operating systems. Combine Windows/Linux coverage data to enforce 100% production branch coverage without excluding platform modules.
+- Agents share a workspace. Respect assigned file ownership and coordinate shared files before editing. Follow the user's current delegation instructions; the remaining work in this task is performed by the primary agent without subagents.
+# Python project engineering requirements
+
+## Scope, project facts, and sources of truth
+
+These requirements govern engineering quality and delivery. Keep the project's
+business purpose, domain model, public behavior, and specialized architecture
+in their existing sections. Read AGENTS.md, README.md, pyproject.toml, the
+feature/status inventory if present, and relevant reference/development
+documentation before changing code.
+
+Record the actual distribution/import names, production source root, supported
+Python versions and platforms, license, dependency policy, version source,
+default branch, release branch, quality command, and documentation entry points.
+Use pyproject.toml for packaging/tool metadata. Resolve license and compatibility
+decisions from the project's choices; do not assume a license, Python minimum,
+fixed version series, or release destination.
+
+Reference documentation owns public contracts; executable guides own workflows;
+tests own behavioral evidence; the feature inventory and README describe
+implemented capability. The changelog records user-visible changes. Requirements
+are not evidence of compliance: identify missing enforcement or documentation
+without claiming that it already exists.
+
+## Design and public API
+
+- Organize production code into small packages by responsibility. Dependencies
+  flow toward core types and domain logic; CLI, filesystem, network, and other
+  adapters depend on the core. Avoid cyclic imports and cross-layer shortcuts.
+  Package __init__.py files curate re-exports without behavioral initialization.
+- Prefer the standard library and existing project mechanisms. Keep runtime
+  dependencies minimal and separate development, documentation, build, and
+  publishing dependencies. Do not introduce speculative abstractions or new
+  backends without a concrete requirement; preserve explicitly chosen native
+  integrations or dependencies.
+- Design typed public APIs with explicit input validation, stable result/error
+  contracts, and documented compatibility. Use __all__ to curate exports and
+  ship py.typed for typed distributions. Distinguish intentional exceptions
+  from unexpected failures; preserve causes and useful context.
+- For asynchronous I/O and resource workflows, prefer async public entry points.
+  Keep synchronous convenience boundaries explicit and prevent nested event
+  loops. Pure calculations need not become async merely for uniformity.
+- Define resource ownership, cleanup order, cancellation behavior, and allowed
+  concurrency scope. Close caller-owned resources explicitly or through context
+  managers. Document whether objects are task-, thread-, or process-safe.
+  Specify cache consistency and recalculation/invalidation rules where caching
+  exists; do not import another project's cache semantics by default.
+- State the actual trust boundary. Do not describe trusted configuration or
+  static capability checks as a hostile-code sandbox. Dynamic execution,
+  reflection, imports, ambient I/O, and connectivity need an explicit role in
+  the design rather than appearing accidentally through convenience helpers.
+
+## Production source requirements
+
+- Each production Python file has at most 200 code-bearing physical lines,
+  excluding imports, declaration/attribute docstrings, pure comments, and blank
+  lines. Multiline signatures, expressions, and runtime strings count by their
+  physical lines. Do not compress statements or embed code in strings to evade
+  the limit. Split by responsibility, not arbitrary line count.
+- Production functions and classes use descriptive names without an underscore
+  prefix. Only required Python protocol methods use dunder spellings. Do not
+  replace meaningful names with generic internal prefixes; curate exports with
+  __all__. These declaration rules do not forbid ordinary private state fields.
+- Every production docstring is English rST. Functions and methods, including
+  nested helpers, explain how they work, every parameter with :param name:,
+  returned values with :returns: unless returning no value, and intentional
+  escaping exceptions with :raises Type:. Value classes document constructor
+  fields and edge cases. Use notes for useful special behavior, not repetition.
+- Document every named constant and coherent constant group, including enums:
+  units or absence of units, actual source, purpose, and choice rationale.
+  Never invent external sources or annotate every ordinary control-flow literal.
+- These size, naming, docstring, and constant requirements apply to production
+  source. Tests and scripts still pass Ruff and strict mypy. Existing explicit
+  project exceptions must be recorded rather than silently broadened.
+
+## Behavioral tests and isolation
+
+- Mirror production subsystem responsibilities in tests. A test file may cover
+  several related implementation modules; each behavior has one obvious owner.
+  Keep integration contracts explicit and reusable fixtures in support modules
+  when actually shared. Do not require one test file per source file.
+- Assert public behavior, observable state, and meaningful diagnostics rather
+  than private method calls or a second implementation of the same algorithm.
+  Cover sunny, rainy, boundary, and composite cases where applicable.
+- Unit tests mock external connectivity, clocks, randomness, and other
+  nondeterminism as needed. Isolate file I/O and enabled logs in a separate
+  TemporaryDirectory per test. CLI test configuration sources are static
+  fixtures declared with their cases. No test should depend on a live account.
+- Include deterministic stress, concurrency, cancellation, and lifecycle/leak
+  tests for relevant behavior in the ordinary full gate. Use property or
+  differential tests where there is a useful invariant or independent oracle.
+  Keep performance benchmarks separate from correctness acceptance.
+- Require 100% production branch coverage, with no threshold reductions,
+  exclusions, ignores, weakened assertions, or invented skips merely to pass.
+  Report genuine platform/dependency skips explicitly and cover supported
+  platforms in the appropriate environment. Use strict test markers/config.
+- If filesystem or temporary-directory permissions block a tool or test, stop
+  that operation and obtain the required permission. Do not relocate temporary
+  files, change temporary environment variables, weaken isolation, skip checks,
+  or change paths solely to bypass the restriction. Continue independent work.
+
+## Change workflow and quality gate
+
+- For a bug: update the relevant English contract; add a behavioral regression
+  test and prove the intended failure; implement the smallest correct fix;
+  prove the test passes; refactor if needed and run focused/full checks.
+- For a feature: prototypes may precede the settled contract, but acceptance
+  requires reference documentation and behavioral tests. Update README,
+  changelog, and the feature inventory when public claims change.
+- For a refactor: pass existing tests first, change production code, pass the
+  same tests, then reorganize test ownership and verify again.
+- Use one authoritative, reproducible quality entry point, preferably
+  python -m scripts.quality if no project equivalent exists. Define its concrete
+  command and environment in this file; identify it as required but unimplemented
+  if it does not exist yet.
+- The gate fails fast through whitespace validation, Ruff, production-policy
+  checks, architecture/capability checks, strict mypy over source/tests/scripts,
+  documentation checks without coverage, and full behavioral tests with branch
+  coverage, including stress tests. Keep all checks in the same environment.
+- Run affected checks during editing. Each completed code-refactor stage and
+  final code handoff runs the full gate. Re-run after new changes, failures, or
+  unresolved concerns; do not repeat unchanged successful suites without cause.
+- Pure prose needs relevant structure and link checks. Execute the exact source
+  of changed examples. Structural documentation changes run the documentation
+  suite once without coverage; avoid chapter/series/full-gate duplication.
+- Produce useful JUnit and machine-readable/browsable coverage reports when
+  supported. Keep generated reports ignored. Record actual commands, results,
+  skips, and tested revisions; never equate configured checks with passing ones.
+
+## Documentation and tutorials
+
+- Keep public documentation in English with reference contracts, practical
+  guides, an accessible README, and a concise implemented-feature inventory.
+  Explain behavior and limitations; never present plans as implemented features.
+- Each tutorial series has a useful standalone introduction and one ordered
+  table of contents. Link every published chapter; do not list planned chapters
+  as available or duplicate the inventory in other documentation entry points.
+  Use stable ordered topic filenames, such as NN-topic-name.md.
+- Mark every complete copyable Python example with a project-specific execution
+  marker, using `<!-- python-doc-exec -->` when no marker exists. Documentation
+  tests extract and execute that exact Markdown source, not a copied equivalent.
+- Teach the smallest useful operation first, add one concept at a time, and end
+  with a realistic composition. Put observable results in inline assertions
+  where practical. Explain why each result follows, what resolves or executes,
+  and who owns state; do not duplicate assertions in expected-result sections.
+- Examples are deterministic and independent. Mock connectivity, isolate file
+  examples in TemporaryDirectory, and close async/resource scopes explicitly.
+  Examples must not use production credentials or persistent external effects.
+- Test chapter discovery against the single table of contents and published
+  files. Update navigation and changelog when adding, renaming, reordering, or
+  retiring chapters. Do not impose word counts, slogans, one test per chapter,
+  or arbitrary exact example counts.
+- Check relative links and anchors, CLI/API inventories, and executable snippets.
+  If a site/export exists, generate it from canonical Markdown after checks,
+  preserve exact examples, and validate navigation/assets. Avoid a competing
+  manually maintained copy of the same documentation.
+
+## Packaging and release integrity
+
+- Declare build metadata, supported Python versions, license, project identity,
+  and tool settings in pyproject.toml. Keep a real license file and accurate
+  compatibility claims; do not silently change the license or support matrix.
+- Keep one authoritative version source or verify all maintained copies agree,
+  including runtime __version__ when present. Respect established version and
+  tag conventions; for new projects use a documented PEP 440-compatible policy
+  with compatibility-aware version increments, not a fixed release series.
+- Use isolated/reproducible build tooling appropriate to the project. Build a
+  wheel and source distribution from the verified release revision; include
+  production code, required runtime resources, typing data, packaging metadata,
+  license, and README. Keep local secrets, reports, environments, development
+  scratch files, and unrelated artifacts out of distributions.
+- A release is a separate requested operation. Prepare a nonempty dated
+  changelog section for its version, retaining unreleased work separately.
+  Check notes and metadata before promotion. Preserve the selected source SHA
+  and artifact identity through the release; never silently replace a version's
+  published tag or distribution.
+- Do not publish, push, merge, delete branches, or contact collaborators merely
+  because this policy was installed. Follow the authorized task scope, preserve
+  unrelated changes, and honor existing approvals without asking again.
+
+## GitHub feature delivery
+
+Use issue -> feature branch -> pull request -> squash merge -> branch cleanup.
+
+1. Create or reuse an issue in the configured GitHub repository for authorized
+   feature/bug work. Record scope, public behavior, and acceptance criteria.
+   Fetch the configured remote and base a feature branch on the current default
+   branch. Prefer codex/<issue-number>-<description> unless the project uses an
+   explicit alternative.
+2. Keep implementation, tests, and documentation together. Follow the change
+   workflow and full gate, commit, push, and open a PR against the default
+   branch. Link the issue with Closes #number. Describe the final behavior,
+   material limitations, and actual verification results.
+3. Wait for all applicable checks on the exact latest PR head, including push
+   and PR verification/builds. Honor required reviews and branch rules. Fix
+   failures and re-check the updated head; earlier green checks do not approve
+   new commits. Intentional workflow-condition exclusions are not missing
+   checks. Keep PR metadata current.
+4. When merging is within scope, squash merge with an expected-head-SHA guard.
+   Preserve draft/review-only requests. Confirm merge and issue closure.
+   Synchronize the local default branch and confirm the merged content.
+5. Verify no post-review work remains on the feature branch before deleting
+   its remote and local copies. Squash merges lose feature-commit ancestry;
+   inspect merged content before a necessary forced local deletion. Finish
+   on the default branch without discarding unrelated work.
+
+## GitHub version publication
+
+Use version update -> verified PR -> squash merge -> fast-forward release
+-> CI quality/build -> PyPI -> matching Git tag and GitHub Release.
+
+1. On a feature or dedicated release-preparation branch, update the canonical
+   version and all maintained copies, including runtime metadata. Finalize a
+   dated changelog section. Validate notes, run the full gate, and verify the
+   latest PR's CI before squash merging.
+2. Select the verified merged commit on the default branch. Fast-forward the
+   persistent release branch to exactly that commit and push it. Never add
+   release-only commits, force the release branch, or publish a feature head.
+3. The configured release workflow verifies version notes and default-branch
+   ancestry, runs the full gate, builds distributions, and publishes those
+   artifacts to PyPI with Trusted Publishing. Use least-privilege permissions,
+   an appropriate publishing environment, and serialized uploads.
+4. After PyPI succeeds, CI creates the matching version tag and GitHub Release
+   at the same source commit with changelog notes and the same wheel/source
+   artifacts attached. Follow the configured tag format; for a new project,
+   use the exact version without a v prefix. Avoid a competing manual release.
+5. Verify completion, not dispatch: latest applicable CI results, successful
+   registry publication, tag target, published Release, attached artifacts, and
+   any applicable documentation deployment. Fetch the tag and report links.
+   If PyPI succeeds and Release creation fails, retry only the failed final
+   stage; never repeat a successful immutable-version upload. After uncertain
+   publication, inspect remote state before any retry.
+6. Keep the default and release branches. For a combined feature/release task,
+   clean up the implementation branch only after publication succeeds and
+   verification shows no unmerged work remains.
+
+Apply this pipeline only when publication is part of the project and requested
+task. A package deliberately not published to PyPI must state its actual release
+destination instead. Missing credentials, environments, CI workflows, or required
+approvals are concrete blockers to the affected stage; do not bypass branch or
+registry controls or claim a release succeeded.

lcl_fastapi-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## Unreleased
+
+No unreleased changes.
+
+## 0.1.0 - 2026-09-11
+
+- Add a typed LCL-powered FastAPI application with native Router and lifespan composition.
+- Add server-generated request IDs, contextual logging, health sampling, and offline Swagger UI.
+- Return HTTP 503 with one failure access log when the upstream Snowflake generator
+  reports clock rollback or sequence exhaustion; do not fabricate a fallback ID.
+- Add Windows Uvicorn and Linux Gunicorn runtimes with local status, log-path, and graceful-stop commands.
+- Propagate application import, configuration, and lifespan startup failures to a
+  nonzero service exit after native worker cleanup on both platforms.
+- Keep master state, control tokens, and POSIX locks owned by their creating
+  process when a forked worker exits and is replaced.
+- Publish worker observations outside the HTTP event loop and wait for active
+  writes before releasing worker resources during shutdown.
+- Use Uvicorn's Winloop integration on Windows so every idle worker keeps publishing
+  observations after startup and replacement without new HTTP connections.
+- Add Nginx and systemd configuration renderers that produce files without performing deployment operations.
+- Establish executable documentation, independent downstream examples, and cross-platform engineering checks.

lcl_fastapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gokurakujoudo
+
+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.

lcl_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: lcl-fastapi
+Version: 0.1.0
+Summary: A lightweight LCL-powered FastAPI service framework
+Project-URL: Repository, https://github.com/gokurakujoudo/lcl-fastapi
+Project-URL: Issues, https://github.com/gokurakujoudo/lcl-fastapi/issues
+Author: gokurakujoudo
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: fastapi<0.142,>=0.141
+Requires-Dist: gunicorn<27,>=26; sys_platform == 'linux'
+Requires-Dist: lclang==1.0.10
+Requires-Dist: psutil<8,>=7.2
+Requires-Dist: uvicorn<0.53,>=0.52
+Requires-Dist: winloop==0.6.3; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: coverage[toml]<8,>=7.10; extra == 'dev'
+Requires-Dist: hatchling<2,>=1.27; extra == 'dev'
+Requires-Dist: httpx<1,>=0.28; extra == 'dev'
+Requires-Dist: mypy<2,>=1.19; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=1.3; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=7; extra == 'dev'
+Requires-Dist: pytest<10,>=9; extra == 'dev'
+Requires-Dist: ruff<1,>=0.14; extra == 'dev'
+Requires-Dist: types-psutil<8,>=7.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lcl-fastapi
+
+`lcl-fastapi` is a small Python 3.14+ service framework combining FastAPI with
+`lclang==1.0.10` configuration, logging, CLI infrastructure, and Snowflake IDs.
+Write business routes, a trusted `.lclcfg` file, and an optional business lifespan.
+The framework owns worker startup, request IDs, health sampling, local operations,
+and bundled offline Swagger UI.
+
+Install the first release with `python -m pip install lcl-fastapi==0.1.0` in a
+Python 3.14 virtual environment. See the [release process](docs/releasing.md)
+for version notes, publication requirements, and artifact verification.
+
+## Start a service
+
+Use a Python 3.14+ virtual environment. Install the built artifact with
+`python -m pip install path/to/lcl_fastapi-0.1.0-py3-none-any.whl`. Dependencies must
+also be installed; offline Swagger means that documentation serving does not
+require a CDN after installation.
+
+Save this application as `app.py` in your downstream project:
+
+<!-- python-doc-exec -->
+```python
+from lcl_fastapi import LclFastAPI, get_logger
+
+service = LclFastAPI()
+
+
+@service.get("/hello")
+async def hello() -> dict[str, str]:
+    logger = await get_logger(__name__)
+    logger.info("hello requested")
+    return {"message": "hello"}
+```
+
+Save `service.lclcfg` alongside it:
+
+```text
+__LCL_VERSION__: 1
+app.name: "example-service"
+app.version: "1.0.0"
+app.target: "app:service"
+server.host: "127.0.0.1"
+server.port: 8080
+server.workers: 1
+logger.file.default.directory: "./logs"
+logger.file.service.filename: f"{app.name}.{worker_pid}.log"
+logger.level: "INFO"
+```
+
+From that project directory, run:
+
+```console
+lcl-fastapi serve -o config service.lclcfg
+```
+
+Open `http://127.0.0.1:8080/hello`, `/health`, or `/docs` in a browser. Swagger's
+JavaScript, stylesheet, favicon, and OpenAPI schema are served locally. Its remote
+validator is disabled. Responses normally carry a newly generated
+`X-Request-ID`; incoming client IDs do not replace it. If the upstream generator
+cannot issue an ID because of clock rollback or exhaustion, the response is 503
+without a fabricated ID and the access log marks the failure. Business logs automatically
+include the current ID, and each worker writes its own file.
+
+Run operations in another terminal using the same configuration file:
+
+```console
+lcl-fastapi status -o config service.lclcfg -o json
+lcl-fastapi logs -o config service.lclcfg
+lcl-fastapi stop -o config service.lclcfg
+```
+
+The CLI deliberately follows `lclang.cli` syntax: `-o config`, not `-c` or
+`--config`; `-o json`, not `--json`. Listener settings have no CLI overrides.
+Log paths are the most recently published live-worker observations, so rollover
+updates are eventually consistent. Stop uses a local control token and waits for
+graceful termination, including business teardown and logger flush.
+
+## Application and deployment boundaries
+
+Windows uses Uvicorn with automatically installed Winloop; Linux uses Gunicorn
+to manage ASGI workers. You run the same
+`lcl-fastapi serve` command on both. Only `127.0.0.1` and `0.0.0.0` are accepted
+listener addresses; the default is loopback. Nginx can provide external HTTPS
+and port forwarding, and systemd is optional. The render commands produce files
+without installing them or running deployment commands.
+
+Business Routers own their prefixes. There is no `api.prefix` setting.
+`server.root_path` is optional external origin metadata such as
+`https://api.example.com:8443`; it does not add a route prefix or set ASGI
+`root_path`. Nginx's actual listener/TLS fields remain independent because a
+public origin may describe an upstream proxy or port mapping.
+
+The supported deployment scope is one service per machine. Configure separate
+machines' Snowflake worker-ID ranges through LCL's environment-variable support.
+Concurrent worker leases do not promise unlimited historical ID uniqueness
+across crashes or rapid reuse. Do not edit configuration while the service is
+running: a replacement worker reads the changed file while older workers retain
+their original values. Use a complete externally managed restart for consistent
+changes. There is no file watcher, hot restart, snapshot distribution, or restart
+API.
+
+User routes with the same HTTP method and exact path override built-in routes.
+Overriding health or documentation replaces those defaults; overriding
+`POST /_lcl/shutdown` can prevent the local stop command from working. The default
+shutdown route is absent from OpenAPI and blocked by generated Nginx configuration.
+There is no business authentication, management port, HTTP log endpoint, or log
+streaming feature.
+
+## Documentation
+
+Two independent downstream projects demonstrate the installed public package:
+[minimal service](examples/minimal/README.md) and
+[composed Router, configuration, and lifespan](examples/composed/README.md).
+GitHub Actions builds the current source wheel, then installs that artifact and
+each example in a separate environment on Windows/Uvicorn and Linux/Gunicorn.
+Each run checks service availability, business and built-in HTTP APIs, all CLI
+commands, and graceful shutdown. The example projects are excluded from the wheel.
+
+- [Application and lifespan](docs/application.md)
+- [Configuration](docs/configuration.md)
+- [Request logging](docs/logging.md)
+- [Health and observations](docs/health.md)
+- [CLI reference](docs/cli.md)
+- [Windows runtime](docs/windows.md) and [Linux runtime](docs/linux.md)
+- [Nginx rendering](docs/nginx.md) and [systemd rendering](docs/systemd.md)
+- [Development plan and acceptance evidence](docs/development-plan.md)
+- [Implemented feature inventory](docs/features.md) and [engineering checks](docs/engineering.md)
+
+The Python package is MIT-licensed. Bundled Swagger UI retains its Apache 2.0
+license and third-party notices; see
+[asset provenance](src/lcl_fastapi/static/swagger/NOTICE.md).

lcl_fastapi-0.1.0/README.md

@@ -0,0 +1,132 @@
+# lcl-fastapi
+
+`lcl-fastapi` is a small Python 3.14+ service framework combining FastAPI with
+`lclang==1.0.10` configuration, logging, CLI infrastructure, and Snowflake IDs.
+Write business routes, a trusted `.lclcfg` file, and an optional business lifespan.
+The framework owns worker startup, request IDs, health sampling, local operations,
+and bundled offline Swagger UI.
+
+Install the first release with `python -m pip install lcl-fastapi==0.1.0` in a
+Python 3.14 virtual environment. See the [release process](docs/releasing.md)
+for version notes, publication requirements, and artifact verification.
+
+## Start a service
+
+Use a Python 3.14+ virtual environment. Install the built artifact with
+`python -m pip install path/to/lcl_fastapi-0.1.0-py3-none-any.whl`. Dependencies must
+also be installed; offline Swagger means that documentation serving does not
+require a CDN after installation.
+
+Save this application as `app.py` in your downstream project:
+
+<!-- python-doc-exec -->
+```python
+from lcl_fastapi import LclFastAPI, get_logger
+
+service = LclFastAPI()
+
+
+@service.get("/hello")
+async def hello() -> dict[str, str]:
+    logger = await get_logger(__name__)
+    logger.info("hello requested")
+    return {"message": "hello"}
+```
+
+Save `service.lclcfg` alongside it:
+
+```text
+__LCL_VERSION__: 1
+app.name: "example-service"
+app.version: "1.0.0"
+app.target: "app:service"
+server.host: "127.0.0.1"
+server.port: 8080
+server.workers: 1
+logger.file.default.directory: "./logs"
+logger.file.service.filename: f"{app.name}.{worker_pid}.log"
+logger.level: "INFO"
+```
+
+From that project directory, run:
+
+```console
+lcl-fastapi serve -o config service.lclcfg
+```
+
+Open `http://127.0.0.1:8080/hello`, `/health`, or `/docs` in a browser. Swagger's
+JavaScript, stylesheet, favicon, and OpenAPI schema are served locally. Its remote
+validator is disabled. Responses normally carry a newly generated
+`X-Request-ID`; incoming client IDs do not replace it. If the upstream generator
+cannot issue an ID because of clock rollback or exhaustion, the response is 503
+without a fabricated ID and the access log marks the failure. Business logs automatically
+include the current ID, and each worker writes its own file.
+
+Run operations in another terminal using the same configuration file:
+
+```console
+lcl-fastapi status -o config service.lclcfg -o json
+lcl-fastapi logs -o config service.lclcfg
+lcl-fastapi stop -o config service.lclcfg
+```
+
+The CLI deliberately follows `lclang.cli` syntax: `-o config`, not `-c` or
+`--config`; `-o json`, not `--json`. Listener settings have no CLI overrides.
+Log paths are the most recently published live-worker observations, so rollover
+updates are eventually consistent. Stop uses a local control token and waits for
+graceful termination, including business teardown and logger flush.
+
+## Application and deployment boundaries
+
+Windows uses Uvicorn with automatically installed Winloop; Linux uses Gunicorn
+to manage ASGI workers. You run the same
+`lcl-fastapi serve` command on both. Only `127.0.0.1` and `0.0.0.0` are accepted
+listener addresses; the default is loopback. Nginx can provide external HTTPS
+and port forwarding, and systemd is optional. The render commands produce files
+without installing them or running deployment commands.
+
+Business Routers own their prefixes. There is no `api.prefix` setting.
+`server.root_path` is optional external origin metadata such as
+`https://api.example.com:8443`; it does not add a route prefix or set ASGI
+`root_path`. Nginx's actual listener/TLS fields remain independent because a
+public origin may describe an upstream proxy or port mapping.
+
+The supported deployment scope is one service per machine. Configure separate
+machines' Snowflake worker-ID ranges through LCL's environment-variable support.
+Concurrent worker leases do not promise unlimited historical ID uniqueness
+across crashes or rapid reuse. Do not edit configuration while the service is
+running: a replacement worker reads the changed file while older workers retain
+their original values. Use a complete externally managed restart for consistent
+changes. There is no file watcher, hot restart, snapshot distribution, or restart
+API.
+
+User routes with the same HTTP method and exact path override built-in routes.
+Overriding health or documentation replaces those defaults; overriding
+`POST /_lcl/shutdown` can prevent the local stop command from working. The default
+shutdown route is absent from OpenAPI and blocked by generated Nginx configuration.
+There is no business authentication, management port, HTTP log endpoint, or log
+streaming feature.
+
+## Documentation
+
+Two independent downstream projects demonstrate the installed public package:
+[minimal service](examples/minimal/README.md) and
+[composed Router, configuration, and lifespan](examples/composed/README.md).
+GitHub Actions builds the current source wheel, then installs that artifact and
+each example in a separate environment on Windows/Uvicorn and Linux/Gunicorn.
+Each run checks service availability, business and built-in HTTP APIs, all CLI
+commands, and graceful shutdown. The example projects are excluded from the wheel.
+
+- [Application and lifespan](docs/application.md)
+- [Configuration](docs/configuration.md)
+- [Request logging](docs/logging.md)
+- [Health and observations](docs/health.md)
+- [CLI reference](docs/cli.md)
+- [Windows runtime](docs/windows.md) and [Linux runtime](docs/linux.md)
+- [Nginx rendering](docs/nginx.md) and [systemd rendering](docs/systemd.md)
+- [Development plan and acceptance evidence](docs/development-plan.md)
+- [Implemented feature inventory](docs/features.md) and [engineering checks](docs/engineering.md)
+
+The Python package is MIT-licensed. Bundled Swagger UI retains its Apache 2.0
+license and third-party notices; see
+[asset provenance](src/lcl_fastapi/static/swagger/NOTICE.md).