splent-feature-elasticsearch 0.1.2__tar.gz

splent_feature_elasticsearch-0.1.2/MANIFEST.in

@@ -0,0 +1,24 @@
+# Frontend assets: the whole tree, not only the compiled bundles.
+#
+# A feature that registers a plain stylesheet with register_asset("css", …)
+# serves it straight from assets/css, and a vendored library lives under
+# assets/vendor. Shipping assets/dist alone put no stylesheet at all in the
+# built package, so every production image came up without its theme, its
+# skin and its editor, while development looked fine because that path
+# installs the checkout in place and reads the files off disk.
+recursive-include src/splent_io/splent_feature_elasticsearch/assets *.css *.js *.map *.json
+recursive-include src/splent_io/splent_feature_elasticsearch/assets *.svg *.png *.jpg *.jpeg *.gif *.webp *.ico
+recursive-include src/splent_io/splent_feature_elasticsearch/assets *.woff *.woff2 *.ttf *.eot
+
+# Build inputs, never shipped.
+prune src/splent_io/splent_feature_elasticsearch/assets/node_modules
+
+# Jinja templates (feature views + hook fragments)
+recursive-include src/splent_io/splent_feature_elasticsearch/templates *.html
+
+# Alembic migration config and scripts
+recursive-include src/splent_io/splent_feature_elasticsearch/migrations *.py *.ini *.mako
+
+# Translations. The .mo is what gettext reads at runtime; the .po
+# travels with it so the next translator has something to edit.
+recursive-include src/splent_io/splent_feature_elasticsearch/translations *.mo *.po *.pot

splent_feature_elasticsearch-0.1.2/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: splent_feature_elasticsearch
+Version: 0.1.2
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: elasticsearch<9,>=8
+
+# splent_feature_elasticsearch
+
+Reusable Elasticsearch infrastructure for SPLENT products (service archetype).
+Ships a single-node Elasticsearch 8.x container and a generic, domain-agnostic
+`ElasticsearchService` that any feature can consume through the service locator.
+
+## What it provides
+
+- `ElasticsearchService` (registered in the service locator):
+  `available()`, `index_name(name)`, `ensure_index(name, mappings=None)`,
+  `index_document(index, id, body)`, `bulk_index(index, documents)`,
+  `delete_document(index, id)`, `refresh_index(name)`,
+  `search(index, query_body)`, `delete_index(name)`, `health()`.
+- Docker: `docker/docker-compose.dev.yml` (host port published) and
+  `docker/docker-compose.prod.yml` (internal-only on `splent_network`),
+  both with a healthcheck and a named `elasticsearch_data` volume.
+- CLI: `splent feature:elasticsearch status`.
+
+## One node, many products
+
+In development the CLI starts each feature as its own compose project, named
+after the feature reference with no product name in it. Every product in the
+workspace therefore talks to the same Elasticsearch container and writes into
+the same data volume. Index names are a flat, node-wide namespace, so two
+products that both index `pages` would overwrite each other's documents and
+answer searches with each other's material.
+
+Every index name handed to the service is prefixed with
+`ELASTICSEARCH_INDEX_PREFIX`, whose shipped value `__PRODUCT__` is resolved to
+the product name by `product:env --merge` and `product:build`. A feature keeps
+using its own short name and never has to know.
+
+```python
+es.ensure_index("pages")          # creates innosoft_app_pages
+es.index_name("pages")            # "innosoft_app_pages"
+```
+
+`splent feature:elasticsearch status` prints the namespace in use, which is the
+quickest way to check that a product is not sharing indices with its neighbour.
+
+An index is a cache and never the authority on visibility. This service stores
+and returns whatever documents it is given; whether a particular reader may see
+a particular hit is decided at request time by the feature that owns the
+material.
+
+## Graceful degradation and typed errors
+
+Elasticsearch is a soft dependency. `available()` never raises, and every other
+operation raises `ElasticsearchError`, never a raw client exception. Two
+subclasses say what happened and what to do about it.
+
+| Exception | Meaning | Usual response |
+| --- | --- | --- |
+| `ElasticsearchUnavailable` | Disabled, or the node could not be reached. | Fall back to a slower search. |
+| `ElasticsearchRequestError` | The node answered and refused the request (malformed query, rejected mapping, missing permission). | Let it surface. Retrying will not help. |
+
+```python
+from splent_framework.services.service_locator import service_proxy
+from splent_io.splent_feature_elasticsearch.services import ElasticsearchUnavailable
+
+es = service_proxy("ElasticsearchService")
+
+try:
+    results = es.search("posts", {"query": {"match": {"title": query}}})
+except ElasticsearchUnavailable:
+    results = fallback_sql_search(query)
+```
+
+## Bulk indexing
+
+A full reindex is thousands of documents, and one HTTP round trip each turns a
+maintenance command into something nobody runs. `bulk_index` consumes any
+iterable lazily, sends batches through the `_bulk` API and reports what
+happened, so a single bad document does not cost you the other 9999.
+
+```python
+report = es.bulk_index(
+    "pages",
+    ({"id": page.id, "body": {"title": page.title, "body": page.text}} for page in pages),
+)
+es.refresh_index("pages")
+# {"indexed": 9999, "failed": 1, "errors": [{"id": 42, "error": "..."}]}
+```
+
+Only a failure of the request itself raises. Per-document failures come back in
+the report, with the error list capped so a broken mapping cannot flood a log.
+
+## Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `ELASTICSEARCH_URL` | `http://localhost:9200` | Node URL. The Docker `.env` sets `http://splent_feature_elasticsearch:9200` for container-to-container access. |
+| `ELASTICSEARCH_ENABLED` | `true` | Feature kill switch. When false all operations degrade immediately. |
+| `ELASTICSEARCH_INDEX_PREFIX` | `splent` | Namespace for this product's indices. The Docker `.env` ships `__PRODUCT__`, resolved to the product name. |
+| `ELASTICSEARCH_HOST_PORT` | `9201` | Host port published in development only. |
+| `ELASTICSEARCH_JAVA_OPTS` | `-Xms512m -Xmx512m` | Heap for the node, read by the production compose file. |
+
+## Tests
+
+```bash
+splent feature:test splent_feature_elasticsearch
+```
+
+Unit tests mock the client boundary, so no network access is required.

splent_feature_elasticsearch-0.1.2/README.md

@@ -0,0 +1,104 @@
+# splent_feature_elasticsearch
+
+Reusable Elasticsearch infrastructure for SPLENT products (service archetype).
+Ships a single-node Elasticsearch 8.x container and a generic, domain-agnostic
+`ElasticsearchService` that any feature can consume through the service locator.
+
+## What it provides
+
+- `ElasticsearchService` (registered in the service locator):
+  `available()`, `index_name(name)`, `ensure_index(name, mappings=None)`,
+  `index_document(index, id, body)`, `bulk_index(index, documents)`,
+  `delete_document(index, id)`, `refresh_index(name)`,
+  `search(index, query_body)`, `delete_index(name)`, `health()`.
+- Docker: `docker/docker-compose.dev.yml` (host port published) and
+  `docker/docker-compose.prod.yml` (internal-only on `splent_network`),
+  both with a healthcheck and a named `elasticsearch_data` volume.
+- CLI: `splent feature:elasticsearch status`.
+
+## One node, many products
+
+In development the CLI starts each feature as its own compose project, named
+after the feature reference with no product name in it. Every product in the
+workspace therefore talks to the same Elasticsearch container and writes into
+the same data volume. Index names are a flat, node-wide namespace, so two
+products that both index `pages` would overwrite each other's documents and
+answer searches with each other's material.
+
+Every index name handed to the service is prefixed with
+`ELASTICSEARCH_INDEX_PREFIX`, whose shipped value `__PRODUCT__` is resolved to
+the product name by `product:env --merge` and `product:build`. A feature keeps
+using its own short name and never has to know.
+
+```python
+es.ensure_index("pages")          # creates innosoft_app_pages
+es.index_name("pages")            # "innosoft_app_pages"
+```
+
+`splent feature:elasticsearch status` prints the namespace in use, which is the
+quickest way to check that a product is not sharing indices with its neighbour.
+
+An index is a cache and never the authority on visibility. This service stores
+and returns whatever documents it is given; whether a particular reader may see
+a particular hit is decided at request time by the feature that owns the
+material.
+
+## Graceful degradation and typed errors
+
+Elasticsearch is a soft dependency. `available()` never raises, and every other
+operation raises `ElasticsearchError`, never a raw client exception. Two
+subclasses say what happened and what to do about it.
+
+| Exception | Meaning | Usual response |
+| --- | --- | --- |
+| `ElasticsearchUnavailable` | Disabled, or the node could not be reached. | Fall back to a slower search. |
+| `ElasticsearchRequestError` | The node answered and refused the request (malformed query, rejected mapping, missing permission). | Let it surface. Retrying will not help. |
+
+```python
+from splent_framework.services.service_locator import service_proxy
+from splent_io.splent_feature_elasticsearch.services import ElasticsearchUnavailable
+
+es = service_proxy("ElasticsearchService")
+
+try:
+    results = es.search("posts", {"query": {"match": {"title": query}}})
+except ElasticsearchUnavailable:
+    results = fallback_sql_search(query)
+```
+
+## Bulk indexing
+
+A full reindex is thousands of documents, and one HTTP round trip each turns a
+maintenance command into something nobody runs. `bulk_index` consumes any
+iterable lazily, sends batches through the `_bulk` API and reports what
+happened, so a single bad document does not cost you the other 9999.
+
+```python
+report = es.bulk_index(
+    "pages",
+    ({"id": page.id, "body": {"title": page.title, "body": page.text}} for page in pages),
+)
+es.refresh_index("pages")
+# {"indexed": 9999, "failed": 1, "errors": [{"id": 42, "error": "..."}]}
+```
+
+Only a failure of the request itself raises. Per-document failures come back in
+the report, with the error list capped so a broken mapping cannot flood a log.
+
+## Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `ELASTICSEARCH_URL` | `http://localhost:9200` | Node URL. The Docker `.env` sets `http://splent_feature_elasticsearch:9200` for container-to-container access. |
+| `ELASTICSEARCH_ENABLED` | `true` | Feature kill switch. When false all operations degrade immediately. |
+| `ELASTICSEARCH_INDEX_PREFIX` | `splent` | Namespace for this product's indices. The Docker `.env` ships `__PRODUCT__`, resolved to the product name. |
+| `ELASTICSEARCH_HOST_PORT` | `9201` | Host port published in development only. |
+| `ELASTICSEARCH_JAVA_OPTS` | `-Xms512m -Xmx512m` | Heap for the node, read by the production compose file. |
+
+## Tests
+
+```bash
+splent feature:test splent_feature_elasticsearch
+```
+
+Unit tests mock the client boundary, so no network access is required.

splent_feature_elasticsearch-0.1.2/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["setuptools>=80.3.1", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "splent_feature_elasticsearch"
+version = "0.1.2"
+readme = "README.md"
+requires-python = ">=3.13"
+
+dependencies = [
+    "elasticsearch>=8,<9",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["*.tests", "*.tests.*"]
+
+[tool.splent]
+cli_version = "1.14.0"
+
+# ── Feature Contract (auto-generated) ────────────────────────────────────────
+# Do not edit manually — re-run `splent feature:contract --write` to refresh.
+# Preserved across refreshes: description, category, tags, env,
+# requires.features_manual (dependencies invisible to static analysis)
+# and provides.routes_manual (routes built from configuration at
+# registration time, which have no literal path to find in source).
+[tool.splent.contract]
+description = "Generic Elasticsearch infrastructure with an ElasticsearchService (index/search) that degrades gracefully"
+archetype = "service"
+
+[tool.splent.contract.provides]
+routes     = []
+blueprints = []
+models     = []
+commands   = ["status"]
+hooks      = []
+services   = ["ElasticsearchService"]
+signals    = []
+translations = ["es"]
+docker     = ["docker-compose.dev.yml", "docker-compose.prod.yml"]
+
+[tool.splent.contract.requires]
+features = []
+env_vars = ["ELASTICSEARCH_ENABLED", "ELASTICSEARCH_INDEX_PREFIX", "SPLENT_APP"]
+signals  = []
+
+[tool.splent.contract.extensible]
+services  = ["ElasticsearchService"]
+templates = []
+models    = []
+hooks     = []
+routes    = false
+
+[tool.splent.contract.docker]
+services   = ["splent_feature_elasticsearch"]
+ports      = ["${ELASTICSEARCH_HOST_PORT}:9200"]
+volumes    = ["elasticsearch_data"]
+networks   = ["splent_network"]
+build      = false
+healthcheck = true
+
+[tool.splent.contract.docker.depends_on]
+services = []
+
+# ── Configuration ─────────────────────────────────────────────────────────
+# ELASTICSEARCH_URL is not here on purpose: its value names the feature's
+# container, and a connection string that points at infrastructure lives in
+# docker/.env.example next to the compose files that define it.
+[tool.splent.config]
+# Kill switch. False makes every operation degrade immediately without ever
+# opening a connection, which is how a deployment runs without a search node.
+ELASTICSEARCH_ENABLED = true
+# Namespace for this product's indices. __PRODUCT__ is resolved to the
+# product name by product:env --merge and product:build; an empty value
+# makes the service fall back to the running product's name, which is the
+# same name. It matters whenever a product is pointed at a node it did not
+# start, because index names are a node-wide namespace.
+ELASTICSEARCH_INDEX_PREFIX = "__PRODUCT__"

splent_feature_elasticsearch-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

splent_feature_elasticsearch-0.1.2/src/splent_feature_elasticsearch.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: splent_feature_elasticsearch
+Version: 0.1.2
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: elasticsearch<9,>=8
+
+# splent_feature_elasticsearch
+
+Reusable Elasticsearch infrastructure for SPLENT products (service archetype).
+Ships a single-node Elasticsearch 8.x container and a generic, domain-agnostic
+`ElasticsearchService` that any feature can consume through the service locator.
+
+## What it provides
+
+- `ElasticsearchService` (registered in the service locator):
+  `available()`, `index_name(name)`, `ensure_index(name, mappings=None)`,
+  `index_document(index, id, body)`, `bulk_index(index, documents)`,
+  `delete_document(index, id)`, `refresh_index(name)`,
+  `search(index, query_body)`, `delete_index(name)`, `health()`.
+- Docker: `docker/docker-compose.dev.yml` (host port published) and
+  `docker/docker-compose.prod.yml` (internal-only on `splent_network`),
+  both with a healthcheck and a named `elasticsearch_data` volume.
+- CLI: `splent feature:elasticsearch status`.
+
+## One node, many products
+
+In development the CLI starts each feature as its own compose project, named
+after the feature reference with no product name in it. Every product in the
+workspace therefore talks to the same Elasticsearch container and writes into
+the same data volume. Index names are a flat, node-wide namespace, so two
+products that both index `pages` would overwrite each other's documents and
+answer searches with each other's material.
+
+Every index name handed to the service is prefixed with
+`ELASTICSEARCH_INDEX_PREFIX`, whose shipped value `__PRODUCT__` is resolved to
+the product name by `product:env --merge` and `product:build`. A feature keeps
+using its own short name and never has to know.
+
+```python
+es.ensure_index("pages")          # creates innosoft_app_pages
+es.index_name("pages")            # "innosoft_app_pages"
+```
+
+`splent feature:elasticsearch status` prints the namespace in use, which is the
+quickest way to check that a product is not sharing indices with its neighbour.
+
+An index is a cache and never the authority on visibility. This service stores
+and returns whatever documents it is given; whether a particular reader may see
+a particular hit is decided at request time by the feature that owns the
+material.
+
+## Graceful degradation and typed errors
+
+Elasticsearch is a soft dependency. `available()` never raises, and every other
+operation raises `ElasticsearchError`, never a raw client exception. Two
+subclasses say what happened and what to do about it.
+
+| Exception | Meaning | Usual response |
+| --- | --- | --- |
+| `ElasticsearchUnavailable` | Disabled, or the node could not be reached. | Fall back to a slower search. |
+| `ElasticsearchRequestError` | The node answered and refused the request (malformed query, rejected mapping, missing permission). | Let it surface. Retrying will not help. |
+
+```python
+from splent_framework.services.service_locator import service_proxy
+from splent_io.splent_feature_elasticsearch.services import ElasticsearchUnavailable
+
+es = service_proxy("ElasticsearchService")
+
+try:
+    results = es.search("posts", {"query": {"match": {"title": query}}})
+except ElasticsearchUnavailable:
+    results = fallback_sql_search(query)
+```
+
+## Bulk indexing
+
+A full reindex is thousands of documents, and one HTTP round trip each turns a
+maintenance command into something nobody runs. `bulk_index` consumes any
+iterable lazily, sends batches through the `_bulk` API and reports what
+happened, so a single bad document does not cost you the other 9999.
+
+```python
+report = es.bulk_index(
+    "pages",
+    ({"id": page.id, "body": {"title": page.title, "body": page.text}} for page in pages),
+)
+es.refresh_index("pages")
+# {"indexed": 9999, "failed": 1, "errors": [{"id": 42, "error": "..."}]}
+```
+
+Only a failure of the request itself raises. Per-document failures come back in
+the report, with the error list capped so a broken mapping cannot flood a log.
+
+## Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `ELASTICSEARCH_URL` | `http://localhost:9200` | Node URL. The Docker `.env` sets `http://splent_feature_elasticsearch:9200` for container-to-container access. |
+| `ELASTICSEARCH_ENABLED` | `true` | Feature kill switch. When false all operations degrade immediately. |
+| `ELASTICSEARCH_INDEX_PREFIX` | `splent` | Namespace for this product's indices. The Docker `.env` ships `__PRODUCT__`, resolved to the product name. |
+| `ELASTICSEARCH_HOST_PORT` | `9201` | Host port published in development only. |
+| `ELASTICSEARCH_JAVA_OPTS` | `-Xms512m -Xmx512m` | Heap for the node, read by the production compose file. |
+
+## Tests
+
+```bash
+splent feature:test splent_feature_elasticsearch
+```
+
+Unit tests mock the client boundary, so no network access is required.

splent_feature_elasticsearch-0.1.2/src/splent_feature_elasticsearch.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+MANIFEST.in
+README.md
+pyproject.toml
+src/splent_feature_elasticsearch.egg-info/PKG-INFO
+src/splent_feature_elasticsearch.egg-info/SOURCES.txt
+src/splent_feature_elasticsearch.egg-info/dependency_links.txt
+src/splent_feature_elasticsearch.egg-info/requires.txt
+src/splent_feature_elasticsearch.egg-info/top_level.txt
+src/splent_io/splent_feature_elasticsearch/__init__.py
+src/splent_io/splent_feature_elasticsearch/commands.py
+src/splent_io/splent_feature_elasticsearch/config.py
+src/splent_io/splent_feature_elasticsearch/services.py
+src/splent_io/splent_feature_elasticsearch/signals.py
+src/splent_io/splent_feature_elasticsearch/translations/messages.pot
+src/splent_io/splent_feature_elasticsearch/translations/es/LC_MESSAGES/messages.mo
+src/splent_io/splent_feature_elasticsearch/translations/es/LC_MESSAGES/messages.po

splent_feature_elasticsearch-0.1.2/src/splent_feature_elasticsearch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

splent_feature_elasticsearch-0.1.2/src/splent_feature_elasticsearch.egg-info/requires.txt

@@ -0,0 +1 @@
+elasticsearch<9,>=8

splent_feature_elasticsearch-0.1.2/src/splent_feature_elasticsearch.egg-info/top_level.txt

@@ -0,0 +1 @@
+splent_io

splent_feature_elasticsearch-0.1.2/src/splent_io/splent_feature_elasticsearch/__init__.py

@@ -0,0 +1,14 @@
+from splent_framework.blueprints.base_blueprint import create_blueprint
+from splent_framework.services.service_locator import register_service
+
+from splent_io.splent_feature_elasticsearch.services import ElasticsearchService
+
+elasticsearch_bp = create_blueprint(__name__)
+
+
+def init_feature(app):
+    register_service(app, "ElasticsearchService", ElasticsearchService)
+
+
+def inject_context_vars(app):
+    return {}

splent_feature_elasticsearch-0.1.2/src/splent_io/splent_feature_elasticsearch/commands.py

@@ -0,0 +1,40 @@
+"""
+CLI commands contributed by splent_feature_elasticsearch.
+
+These commands are auto-discovered by the framework and exposed in the
+SPLENT CLI under the ``feature:elasticsearch`` group.
+
+Usage::
+
+    splent feature:elasticsearch status
+"""
+
+import click
+
+from splent_io.splent_feature_elasticsearch.services import ElasticsearchService
+
+
+@click.command("status")
+def status():
+    """Show the Elasticsearch connection status for the active product."""
+    service = ElasticsearchService()
+    info = service.health()
+
+    click.echo(f"  URL:     {info['url']}")
+    click.echo(f"  Enabled: {'yes' if info['enabled'] else 'no'}")
+    # The node is shared by every product in the workspace, so the prefix is
+    # the only thing telling one product's indices from another's.
+    click.echo(f"  Indices: {info['index_prefix']}_*")
+
+    if not info["enabled"]:
+        click.secho("  Status:  disabled (ELASTICSEARCH_ENABLED=false)", fg="yellow")
+        return
+
+    if info["available"]:
+        click.secho("  Status:  available", fg="green")
+    else:
+        click.secho("  Status:  unreachable", fg="red")
+        raise SystemExit(1)
+
+
+cli_commands = [status]

splent_feature_elasticsearch-0.1.2/src/splent_io/splent_feature_elasticsearch/config.py

@@ -0,0 +1,46 @@
+"""elasticsearch feature configuration.
+
+Injects the Elasticsearch connection settings into Flask app.config.
+
+The default URL targets a local node (http://localhost:9200). When the
+feature's Docker service is used, the product's .env sets
+ELASTICSEARCH_URL=http://splent_feature_elasticsearch:9200 so containers
+resolve the node by service name on splent_network (same pattern as
+splent_feature_redis).
+
+ELASTICSEARCH_INDEX_PREFIX is what keeps two products apart on that node. In
+development every product in the workspace reaches the same container and the
+same data volume, because the CLI starts the feature as its own compose
+project named after the feature and not after any product. Index names are a
+node-wide namespace, so without a prefix two products indexing "pages" would
+overwrite each other's documents. The feature's .env ships the value
+__PRODUCT__, which product:env --merge and product:build resolve to the
+product name.
+
+To regenerate from source code: splent feature:inject-config splent_feature_elasticsearch
+"""
+
+import os
+
+
+def _as_bool(value: str) -> bool:
+    return value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def inject_config(app):
+    app.config.update(
+        {
+            "ELASTICSEARCH_URL": os.getenv(
+                "ELASTICSEARCH_URL", "http://localhost:9200"
+            ),
+            "ELASTICSEARCH_ENABLED": _as_bool(
+                os.getenv("ELASTICSEARCH_ENABLED", "true")
+            ),
+            # Empty on purpose. The service falls back to the name of the
+            # product that is running, which is the namespace wanted and is
+            # always known inside one. A shared literal here would be a
+            # default that every misconfigured product agrees on, which is
+            # exactly the collision this variable exists to prevent.
+            "ELASTICSEARCH_INDEX_PREFIX": os.getenv("ELASTICSEARCH_INDEX_PREFIX", ""),
+        }
+    )

splent_feature_elasticsearch-0.1.2/src/splent_io/splent_feature_elasticsearch/services.py

@@ -0,0 +1,469 @@
+"""Generic Elasticsearch access for SPLENT products (infrastructure service).
+
+A thin, domain-agnostic wrapper around the official ``elasticsearch`` client.
+It owns no relational entity, so it is a plain service rather than a
+repository-backed one. Consumer features decide *what* to index and *how* to
+query; this service only provides the transport:
+
+    es = service_proxy("ElasticsearchService")
+    if es.available():
+        es.ensure_index("posts", mappings={...})
+        es.index_document("posts", post.id, {"title": post.title})
+
+One node, many products
+-----------------------
+In development the CLI starts each feature as its own compose project, named
+after the feature reference with no product name in it, so every product in
+the workspace talks to the same Elasticsearch container and writes into the
+same data volume. Index names are a flat, node-wide namespace, which means
+two products that both index "pages" would overwrite each other's documents
+and answer searches with each other's material. Every index name given to
+this service is therefore prefixed with ELASTICSEARCH_INDEX_PREFIX, which the
+product's .env resolves to the product name, so "pages" becomes
+"innosoft_app_pages" over here and "diversolab_app_pages" over there. Callers
+keep passing their own short names; ``index_name()`` tells them the real one
+when they need to see it.
+
+An index is a cache and never an authority on who may read what. This service
+stores and returns whatever documents it is given, and the feature that owns
+the material decides at request time whether a particular reader may see a
+particular hit.
+
+Failure modes
+-------------
+Elasticsearch is a soft dependency, so failures are typed rather than raw:
+``available()`` never raises, and every other method raises
+:class:`ElasticsearchError`, either :class:`ElasticsearchUnavailable` when the
+node could not be reached or :class:`ElasticsearchRequestError` when the node
+answered and refused the request. Nothing from the underlying client escapes.
+
+Configuration (see config.py): ELASTICSEARCH_URL, ELASTICSEARCH_ENABLED,
+ELASTICSEARCH_INDEX_PREFIX. All are read from app.config when a Flask app
+context is active, falling back to the environment so the service also works
+in plain scripts and tests.
+"""
+
+import logging
+import os
+from contextlib import contextmanager
+from itertools import batched
+
+from flask import current_app, has_app_context
+
+logger = logging.getLogger(__name__)
+
+# Client-wide request timeout (seconds). Deliberately short so an absent
+# Elasticsearch fails fast instead of hanging requests.
+REQUEST_TIMEOUT = 5
+
+DEFAULT_URL = "http://localhost:9200"
+
+# Namespace used when ELASTICSEARCH_INDEX_PREFIX is unset, which happens in
+# bare scripts and tests but not in a product: product:env resolves the
+# __PRODUCT__ placeholder shipped in this feature's .env into the product name.
+# Documents per _bulk request. Elastic's own advice is to keep a bulk body in
+# the low megabytes, and a few hundred small documents sit well inside that
+# while turning a ten thousand page reindex into twenty requests.
+DEFAULT_BULK_BATCH_SIZE = 500
+
+# How many per-document failures a bulk report carries back. A reindex against
+# a broken mapping fails on every single document, and handing ten thousand
+# error strings to a CLI command helps nobody; the counts stay exact.
+MAX_REPORTED_BULK_FAILURES = 20
+
+
+class ElasticsearchError(RuntimeError):
+    """Base class for every failure this service reports.
+
+    Public methods let nothing from the underlying client escape, so a caller
+    that treats Elasticsearch as a soft dependency can catch this one class
+    and be sure it has caught everything. Which subclass arrives says whether
+    falling back is the right answer or whether there is a bug to fix.
+    """
+
+
+class ElasticsearchUnavailable(ElasticsearchError):
+    """The node could not be reached, or the feature is switched off.
+
+    Nothing is wrong with the request, so consumers degrade and carry on::
+
+        try:
+            results = es.search("posts", query)
+        except ElasticsearchUnavailable:
+            results = fallback_search(query)
+    """
+
+
+class ElasticsearchRequestError(ElasticsearchError):
+    """The node answered, refusing the request.
+
+    A malformed query body, a field the mapping will not accept, a missing
+    permission. These used to travel up as raw client exceptions, so a caller
+    that had carefully handled the unreachable case still returned a 500 the
+    first time somebody mistyped a query. Retrying will not help and a silent
+    fallback would hide the defect, so consumers normally let this surface.
+    """
+
+
+# One client per URL, shared across service instances. service_proxy()
+# instantiates a fresh service on every access, so per-instance caching
+# would recreate the client constantly.
+_clients: dict[str, object] = {}
+
+
+def _build_client(url: str):
+    """Create the raw Elasticsearch client. Isolated so tests can patch it."""
+    from elasticsearch import Elasticsearch
+
+    return Elasticsearch(hosts=[url], request_timeout=REQUEST_TIMEOUT)
+
+
+def reset_client_cache() -> None:
+    """Drop cached clients (used by tests and after config changes)."""
+    _clients.clear()
+
+
+def _describe_bulk_error(error) -> str:
+    """The one useful line out of a per-item _bulk error object.
+
+    Elasticsearch reports item failures as a nested object whose ``reason``
+    already reads as a sentence, so that is what a log line or a CLI report
+    wants; the type is the fallback for the rare error without one.
+    """
+    if not isinstance(error, dict):
+        return str(error)
+    return error.get("reason") or error.get("type") or "unknown error"
+
+
+class ElasticsearchService:
+    """Minimal generic API over an Elasticsearch cluster."""
+
+    # ── Configuration ────────────────────────────────────────────────────
+
+    def _cfg(self, key: str, default):
+        if has_app_context():
+            return current_app.config.get(key, os.getenv(key, default))
+        return os.getenv(key, default)
+
+    @property
+    def url(self) -> str:
+        return self._cfg("ELASTICSEARCH_URL", DEFAULT_URL)
+
+    @property
+    def enabled(self) -> bool:
+        value = self._cfg("ELASTICSEARCH_ENABLED", "true")
+        if isinstance(value, str):
+            return value.strip().lower() in ("1", "true", "yes", "on")
+        return bool(value)
+
+    @property
+    def index_prefix(self) -> str:
+        """The namespace this product's indices live under on the node.
+
+        Every product on a node shares one flat namespace, and in
+        development they really do share a node: the CLI starts each feature
+        as its own compose project named after the feature, with no product
+        in the name, so one Elasticsearch serves every product in the
+        workspace. Two products that landed on the same prefix would write
+        into each other's indices, and a reindex by either would delete the
+        other's.
+
+        So an unset prefix, or one still holding the unresolved __PRODUCT__
+        placeholder because no product ever merged this feature's .env,
+        falls back to the name of the product that is running, which is
+        exactly the namespace wanted and is always known inside a product.
+        It does NOT fall back to a shared constant: sharing is the failure
+        being prevented, and a default that every misconfigured product
+        agrees on fails in the direction that hurts.
+        """
+        value = str(self._cfg("ELASTICSEARCH_INDEX_PREFIX", "")).strip()
+        if not value or "__PRODUCT__" in value:
+            value = str(os.getenv("SPLENT_APP", "")).strip()
+        if not value:
+            raise ElasticsearchRequestError(
+                "No index prefix and no SPLENT_APP, so there is no way to tell "
+                "this product's indices from another product's on the same "
+                "node. Set ELASTICSEARCH_INDEX_PREFIX."
+            )
+        # Elasticsearch rejects an index name containing an uppercase letter,
+        # and product names are free to carry one.
+        return value.lower()
+
+    def index_name(self, name: str) -> str:
+        """The real index name behind a caller's logical one.
+
+        Callers work in short names ("pages") and this service puts them in
+        the product's namespace. Use this when the real name has to be shown,
+        logged, or handed to something that talks to the node directly.
+
+        Prefixing a name that already carries the prefix is a no-op, so a
+        caller that reads a name back out of here and passes it to search()
+        still queries its own index rather than an empty
+        "prefix_prefix_pages" that would quietly return no results.
+        """
+        prefix = self.index_prefix
+        name = str(name)
+        if name == prefix or name.startswith(f"{prefix}_"):
+            return name
+        return f"{prefix}_{name}"
+
+    # ── Client ───────────────────────────────────────────────────────────
+
+    def _client(self):
+        """Lazy, cached client. Raises ElasticsearchUnavailable when disabled."""
+        if not self.enabled:
+            raise ElasticsearchUnavailable(
+                "Elasticsearch is disabled (ELASTICSEARCH_ENABLED=false)."
+            )
+        url = self.url
+        client = _clients.get(url)
+        if client is None:
+            client = _build_client(url)
+            _clients[url] = client
+        return client
+
+    # ── Error translation ────────────────────────────────────────────────
+
+    @staticmethod
+    def _rejection_errors() -> tuple:
+        """Client exceptions meaning the request itself was not acceptable.
+
+        SerializationError is a TransportError by inheritance, but it is
+        raised over a body this caller built rather than over a network that
+        went away, so it belongs with the rejections. That is also why this
+        tuple has to be tried before the transport one.
+        """
+        from elasticsearch import ApiError, SerializationError
+
+        return (ApiError, SerializationError)
+
+    @staticmethod
+    def _transport_errors() -> tuple:
+        """Client exceptions meaning the request never reached an answer.
+
+        The two named ones are what a stopped container produces and what
+        consumers see day to day; TransportError covers the rest of the family
+        (TLS handshake, node sniffing) so nothing raw escapes.
+        """
+        from elasticsearch import ConnectionError as ESConnectionError
+        from elasticsearch import ConnectionTimeout, TransportError
+
+        return (ESConnectionError, ConnectionTimeout, TransportError)
+
+    def _unavailable(self, exc: Exception) -> ElasticsearchUnavailable:
+        message = f"Elasticsearch at {self.url} is unreachable: {exc}"
+        logger.warning(message)
+        return ElasticsearchUnavailable(message)
+
+    def _rejected(self, exc: Exception) -> ElasticsearchRequestError:
+        message = f"Elasticsearch at {self.url} rejected the request: {exc}"
+        logger.warning(message)
+        return ElasticsearchRequestError(message)
+
+    @contextmanager
+    def _translated_errors(self):
+        """Run a client call and report its failure as one of our two kinds.
+
+        Every public method wraps its call in this, which is what makes the
+        promise in the module docstring true: catching ElasticsearchError
+        catches everything this service can do to a caller.
+        """
+        try:
+            yield
+        except self._rejection_errors() as exc:
+            raise self._rejected(exc) from exc
+        except self._transport_errors() as exc:
+            raise self._unavailable(exc) from exc
+
+    # ── Public API ───────────────────────────────────────────────────────
+
+    def available(self) -> bool:
+        """True when Elasticsearch is enabled and answers a ping. Never raises."""
+        if not self.enabled:
+            return False
+        try:
+            return bool(self._client().ping())
+        except Exception as exc:
+            logger.debug("Elasticsearch ping failed for %s: %s", self.url, exc)
+            return False
+
+    def ensure_index(self, name: str, mappings: dict | None = None) -> bool:
+        """Create an index if it does not exist. Idempotent.
+
+        Returns True when the index was created, False when it already existed.
+        """
+        from elasticsearch import BadRequestError
+
+        client = self._client()
+        index = self.index_name(name)
+        with self._translated_errors():
+            try:
+                if client.indices.exists(index=index):
+                    return False
+                kwargs = {}
+                if mappings:
+                    kwargs["mappings"] = mappings
+                client.indices.create(index=index, **kwargs)
+                return True
+            except BadRequestError as exc:
+                # Two workers racing to create the same index. The loser sees
+                # resource_already_exists_exception, still a success for us.
+                if "resource_already_exists_exception" in str(exc.message):
+                    return False
+                raise
+
+    def index_document(self, index: str, id: str, body: dict) -> dict:
+        """Index (create or overwrite) a document. Returns the ES response."""
+        client = self._client()
+        with self._translated_errors():
+            return client.index(index=self.index_name(index), id=id, document=body)
+
+    def bulk_index(
+        self,
+        index: str,
+        documents,
+        batch_size: int = DEFAULT_BULK_BATCH_SIZE,
+    ) -> dict:
+        """Index many documents in as few requests as possible.
+
+        ``documents`` is any iterable of ``{"id": ..., "body": {...}}`` and is
+        consumed lazily, so a full reindex can stream out of a query without
+        ever holding the whole corpus in memory. Reindexing a wiki is
+        thousands of documents, and one HTTP round trip each turns a
+        maintenance command into something nobody runs.
+
+        Returns ``{"indexed": int, "failed": int, "errors": [...]}``. A
+        document the node refuses does not abort the run: ten thousand pages
+        that trip over one bad field should still leave 9999 searchable, and
+        the caller gets exact counts plus a capped sample of reasons to log.
+        Only a failure of the request itself raises.
+        """
+        client = self._client()
+        real_index = self.index_name(index)
+
+        indexed = 0
+        failed = 0
+        errors: list[dict] = []
+
+        def record_failure(doc_id, reason) -> None:
+            nonlocal failed
+            failed += 1
+            if len(errors) < MAX_REPORTED_BULK_FAILURES:
+                errors.append({"id": doc_id, "error": reason})
+
+        for batch in batched(documents, max(1, int(batch_size))):
+            operations: list[dict] = []
+            for document in batch:
+                doc_id = document.get("id")
+                if doc_id is None:
+                    # Without a stable id the node invents one, so every run
+                    # would append another copy instead of overwriting.
+                    record_failure(None, "document has no id")
+                    continue
+                operations.append({"index": {"_id": str(doc_id)}})
+                operations.append(document.get("body") or {})
+
+            if not operations:
+                continue
+
+            with self._translated_errors():
+                response = client.bulk(index=real_index, operations=operations)
+
+            items = response.get("items") or []
+            if not response.get("errors"):
+                # One item per document, but fall back to the operation count
+                # for a node that answered without the detail.
+                indexed += len(items) if items else len(operations) // 2
+                continue
+
+            # One key per item, named after the action ("index"), holding the
+            # per-document result.
+            for item in items:
+                result = next(iter(item.values()), {}) if item else {}
+                error = result.get("error")
+                if error:
+                    record_failure(result.get("_id"), _describe_bulk_error(error))
+                else:
+                    indexed += 1
+
+        return {"indexed": indexed, "failed": failed, "errors": errors}
+
+    def refresh_index(self, name: str) -> bool:
+        """Make just-indexed documents searchable immediately.
+
+        Elasticsearch is near-real-time (documents become visible after the
+        next periodic refresh, ~1s): consumers that index and search within
+        the same request call this after their indexing loop.
+
+        An index that is not there is not an error, the same way deleting a
+        missing one is not: asking for documents to become searchable when
+        there are none has already happened. It used to raise, which put a
+        four hundred and four in front of anyone building an index for the
+        first time and made a working reindex read like a broken one.
+        Returns whether there was anything to refresh.
+        """
+        from elasticsearch import NotFoundError
+
+        client = self._client()
+        with self._translated_errors():
+            try:
+                client.indices.refresh(index=self.index_name(name))
+                return True
+            except NotFoundError:
+                logger.debug("Index '%s' not found; nothing to refresh.", name)
+                return False
+
+    def delete_document(self, index: str, id: str) -> bool:
+        """Delete a document. Returns False (without failing) if it is missing."""
+        from elasticsearch import NotFoundError
+
+        client = self._client()
+        with self._translated_errors():
+            try:
+                client.delete(index=self.index_name(index), id=id)
+                return True
+            except NotFoundError:
+                logger.debug(
+                    "Document '%s' not found in '%s'; nothing to delete.", id, index
+                )
+                return False
+
+    def search(self, index: str, query_body: dict) -> dict:
+        """Run a raw query body against an index.
+
+        Returns ``{"hits": [<raw hit dicts>], "total": <int>}`` so consumers
+        get both ``_source`` and metadata (``_id``, ``_score``) per hit. What
+        comes back is a list of candidates, not a list of things the reader is
+        allowed to see; deciding that is the owning feature's job.
+        """
+        client = self._client()
+        with self._translated_errors():
+            response = client.search(index=self.index_name(index), body=query_body)
+
+        hits = response["hits"]["hits"]
+        total = response["hits"]["total"]
+        if isinstance(total, dict):  # ES >= 7 shape: {"value": n, "relation": "eq"}
+            total = total.get("value", len(hits))
+        return {"hits": list(hits), "total": total}
+
+    def delete_index(self, name: str) -> bool:
+        """Delete an index. Returns False (without failing) if it is missing."""
+        from elasticsearch import NotFoundError
+
+        client = self._client()
+        with self._translated_errors():
+            try:
+                client.indices.delete(index=self.index_name(name))
+                return True
+            except NotFoundError:
+                logger.debug("Index '%s' not found; nothing to delete.", name)
+                return False
+
+    def health(self) -> dict:
+        """Status snapshot used by the `feature:elasticsearch status` command."""
+        return {
+            "url": self.url,
+            "enabled": self.enabled,
+            "index_prefix": self.index_prefix,
+            "available": self.available(),
+        }

splent_feature_elasticsearch-0.1.2/src/splent_io/splent_feature_elasticsearch/signals.py

@@ -0,0 +1,19 @@
+"""
+Signals for splent_feature_elasticsearch.
+
+Use ``define_signal`` to declare signals this feature emits.
+Use ``connect_signal`` to listen to signals from other features.
+
+Examples::
+
+    # Define a signal (this feature emits it):
+    from splent_framework.signals.signal_utils import define_signal
+    item_created = define_signal("item-created", "splent_feature_elasticsearch")
+
+    # Connect to a signal from another feature:
+    from splent_framework.signals.signal_utils import connect_signal
+
+    @connect_signal("user-registered", "splent_feature_elasticsearch")
+    def on_user_registered(sender, user, **kwargs):
+        pass
+"""

splent_feature_elasticsearch-0.1.2/src/splent_io/splent_feature_elasticsearch/translations/es/LC_MESSAGES/messages.po

@@ -0,0 +1,20 @@
+# Spanish translations for PROJECT.
+# Copyright (C) 2026 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2026-07-30 15:44+0000\n"
+"PO-Revision-Date: 2026-07-30 15:45+0000\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: es\n"
+"Language-Team: es <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+

splent_feature_elasticsearch-0.1.2/src/splent_io/splent_feature_elasticsearch/translations/messages.pot

@@ -0,0 +1,19 @@
+# Translations template for PROJECT.
+# Copyright (C) 2026 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2026-07-30 15:44+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+