imbi-api 2.32.2__tar.gz → 2.32.3__tar.gz

{imbi_api-2.32.2 → imbi_api-2.32.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: imbi-api
-Version: 2.32.2
+Version: 2.32.3
 Summary: Imbi is a DevOps Service Management Platform designed to provide an efficient way to manage a large environment that contains many services and applications.
 Author-email: Alex Campbell <alexc@aweber.com>, Dave Shawley <daves@aweber.com>, "Gavin M. Roy" <gavinr@aweber.com>
 License-Expression: BSD-3-Clause
@@ -19,7 +19,7 @@ Requires-Dist: cyclonedx-python-lib<12,>=11.7
 Requires-Dist: fastapi
 Requires-Dist: filetype
 Requires-Dist: httpx<1,>=0.28.1
-Requires-Dist: imbi-common[databases,llm,sentry,server]==2.32.2
+Requires-Dist: imbi-common[databases,llm,sentry,server]==2.32.3
 Requires-Dist: jinja2
 Requires-Dist: jsonpatch>=1.33
 Requires-Dist: mcp>=1.26.0

{imbi_api-2.32.2 → imbi_api-2.32.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "imbi-api"
-version = "2.32.2"
+version = "2.32.3"
 description = "Imbi is a DevOps Service Management Platform designed to provide an efficient way to manage a large environment that contains many services and applications."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -28,7 +28,7 @@ dependencies = [
   "fastapi",
   "filetype",
   "httpx>=0.28.1,<1",
-  "imbi-common[databases,llm,sentry,server]==2.32.2",
+  "imbi-common[databases,llm,sentry,server]==2.32.3",
   "jinja2",
   "jsonpatch>=1.33",
   "mcp>=1.26.0",

{imbi_api-2.32.2 → imbi_api-2.32.3}/src/imbi/api/endpoints/project_deployments.py

@@ -1545,6 +1545,104 @@ async def fetch_release_notes_for_tag(
     )
 
 
+async def resolve_committish_for_tag(
+    db: graph.Graph,
+    *,
+    org_slug: str,
+    project_id: str,
+    tag: str,
+    auth: permissions.AuthContext,
+) -> str | None:
+    """Resolve ``tag`` to the short committish it points at.
+
+    The release-create path uses this when a caller supplies a tag but no
+    commit -- a source host's ``release`` webhook names the tag and the
+    branch it was cut from, never the SHA.  The lookup goes through the
+    deployment capability rather than the ClickHouse ``tags`` table
+    because the two race: the ``release`` delivery lands before commit
+    sync records the tag (32s apart on the delivery that motivated this),
+    so the table is reliably empty at exactly the moment this is called.
+    The remote, by contrast, has the tag by definition -- it is what it
+    just announced.
+
+    ``None`` means the answer is *no commit*, and the caller may reject
+    the release on it: the remote positively reported the ref does not
+    exist (HTTP 404/422), no deployment capability is bound to the
+    project at all, or the plugin does not implement
+    ``resolve_committish``.  Every other failure raises instead -- the
+    same distinction ``resolve_remote_tags`` draws between ``'absent'``
+    and ``'error'``, and for the same reason: a caller that refuses a
+    release on ``None`` must never read unreachability as absence.  A
+    timed-out, rate-limited, unauthorized or uncredentialed lookup
+    would otherwise turn a "retry shortly" into a terminal "your tag is
+    invalid".  Both the capability resolution and the call itself can
+    fail either way, so both are sorted, not just the call.
+    """
+    try:
+        resolved, ctx, credentials = await _resolve_and_context(
+            db, org_slug, project_id, auth, best_effort_identity=True
+        )
+    except fastapi.HTTPException as exc:
+        # Only 404 -- "no integration provides the deployment
+        # capability" -- means this project has no way to name a
+        # commit.  The other answers here are failures to *ask*: a
+        # missing service credential is a deliberate, retryable 503
+        # (see ``_resolve_and_context``), a 403 is an authorization
+        # problem, and a 400 means the capability is bound more than
+        # once and needs ``?source=``.  Reporting any of those as an
+        # absent tag is the same mistake as swallowing the timeout.
+        if exc.status_code == 404:
+            return None
+        raise
+    handler = _handler(resolved)
+    try:
+        commit = await call_with_timeout(
+            handler.resolve_committish(
+                ctx, _resolve_credentials(ctx, credentials), tag
+            )
+        )
+    except NotImplementedError:
+        return None
+    except plugin_errors.PluginRateLimited:
+        raise
+    except fastapi.HTTPException:
+        # ``call_with_timeout`` raises 503 + ``Retry-After`` on timeout.
+        raise
+    except httpx.HTTPStatusError as exc:
+        # 404 is the remote saying "no such ref"; GitHub answers 422 for
+        # a ref it cannot even parse.  Everything else (403, 5xx) is the
+        # remote failing to answer, not answering "no".
+        if exc.response.status_code in (404, 422):
+            return None
+        LOGGER.warning(
+            'committish lookup for project=%s tag=%s failed with %s',
+            project_id,
+            tag,
+            exc.response.status_code,
+        )
+        raise fastapi.HTTPException(
+            status_code=503,
+            detail=f'Could not reach the source host to resolve {tag!r}',
+            headers={'Retry-After': '5'},
+        ) from exc
+    except httpx.HTTPError as exc:
+        # Transport-level: connect, read, protocol.  Transient, so it
+        # must not read as "the tag does not exist" either.
+        LOGGER.warning(
+            'committish lookup for project=%s tag=%s failed: %r',
+            project_id,
+            tag,
+            exc,
+        )
+        raise fastapi.HTTPException(
+            status_code=503,
+            detail=f'Could not reach the source host to resolve {tag!r}',
+            headers={'Retry-After': '5'},
+        ) from exc
+    await persist_link_writeback(db, ctx)
+    return versioning.short_committish(commit.sha)
+
+
 async def backfill_release_notes(
     db: graph.Graph,
     *,

{imbi_api-2.32.2 → imbi_api-2.32.3}/src/imbi/api/endpoints/releases.py

@@ -74,26 +74,53 @@ _RELEASE_HYDRATION_SEMAPHORE = asyncio.Semaphore(
 
 
 class ReleaseCreate(pydantic.BaseModel):
-    """Request body for creating a release."""
+    """Request body for creating a release.
+
+    At least one of ``committish`` / ``tag`` is required.  A source
+    host's *release* notification carries no commit -- GitHub's
+    ``release`` payload offers only ``target_commitish``, which is the
+    branch the release was cut from (``main`` on 99.7% of deliveries)
+    rather than a SHA -- so a caller that has only the tag omits the
+    committish and the endpoint resolves it through the project's
+    deployment capability.
+    """
 
     model_config = pydantic.ConfigDict(extra='forbid')
 
     tag: str | None = None
     committish: typing.Annotated[
-        str,
+        str | None,
         pydantic.Field(
             pattern=r'^[0-9a-f]{7}$',
             description=(
                 'Short commit SHA (7 lowercase hexadecimal chars) '
-                'identifying the source revision for this release.'
+                'identifying the source revision for this release. '
+                'Optional when a tag is supplied: the tag is then '
+                'resolved to its commit through the deployment '
+                'capability.'
             ),
         ),
-    ]
+    ] = None
     title: str
     description: str | None = None
     links: list[models.ReleaseLink] = []
     created_by: str | None = None
 
+    @pydantic.model_validator(mode='after')
+    def validate_identity(self) -> typing.Self:
+        """Reject a body that identifies no revision at all.
+
+        An empty ``tag`` is normalized to ``None`` first, so it cannot
+        reach the graph: the untagged-release lookup treats ``''`` and
+        NULL alike, and a node stored with ``''`` would be matched as
+        untagged but could not then be named.
+        """
+        if self.tag == '':
+            self.tag = None
+        if not self.committish and not self.tag:
+            raise ValueError('one of committish or tag is required')
+        return self
+
 
 class ReleaseUpdate(pydantic.BaseModel):
     """JSON Patch-compatible release shape.
@@ -308,6 +335,107 @@ async def _fetch_release(
     )
 
 
+# Per-project release identity, in priority order.
+#
+# A tag is the identity whenever one exists: it names one shippable
+# artifact, while the commit it points at moves (the release workflow
+# bumps the version, then tags the bump commit).  Keying on the
+# committish is what let the post-bump SHA miss the node Imbi had
+# already created.
+#
+# The second clause is the cross-webhook case.  A ``deployment_status``
+# delivery creates the release from a commit alone, then the ``release``
+# delivery names the same artifact by tag; matching on the tag alone
+# misses that node and creates a sibling for one release.  A tagged
+# create therefore also claims an *untagged* node carrying its commit.
+# The reverse is deliberately not true -- an untagged create never
+# claims a tagged node, because a tag is a narrower identity than the
+# commit under it and two tags can share one commit.
+#
+# AGE has no NULL equality, so nullable comparisons go through COALESCE
+# to a sentinel.
+_RELEASE_BY_TAG: typing.Final[typing.LiteralString] = """
+MATCH (p:Project {{id: {project_id}}})-[:HAS_RELEASE]->(r:Release)
+WHERE r.tag = {tag}
+RETURN r.id AS id
+"""
+
+_RELEASE_BY_COMMITTISH: typing.Final[typing.LiteralString] = """
+MATCH (p:Project {{id: {project_id}}})-[:HAS_RELEASE]->(r:Release)
+WHERE r.committish = {committish} AND COALESCE(r.tag, '') = ''
+RETURN r.id AS id
+"""
+
+# The predicate has to be the same one ``_RELEASE_BY_COMMITTISH``
+# matched on.  ``COALESCE(r.tag, {tag})`` replaces only NULL, so a node
+# stored with an empty-string tag would be matched as untagged, adopted,
+# and left untagged -- dropping the incoming tag and answering 200 with
+# a release that still has none.  ``ReleaseCreate`` now normalizes ``''``
+# to NULL so this endpoint cannot create such a node, but rows predating
+# that (or written by another client) still have to be nameable.
+_RELEASE_ADOPT_TAG: typing.Final[typing.LiteralString] = """
+MATCH (r:Release {{id: {release_id}}})
+SET r.tag = CASE WHEN COALESCE(r.tag, '') = '' THEN {tag} ELSE r.tag END,
+    r.updated_at = {now}
+RETURN r.id AS id
+"""
+
+
+class _ExistingRelease(typing.NamedTuple):
+    """A release a create would duplicate, and how it was matched."""
+
+    id: str
+    #: False when the match came from the committish, meaning the node is
+    #: untagged and a tagged create should adopt it.
+    by_tag: bool
+
+
+async def _find_existing_release(
+    db: graph.Graph,
+    *,
+    project_id: str,
+    tag: str | None,
+    committish: str,
+) -> _ExistingRelease | None:
+    """Return the release this create would duplicate, if any."""
+    if tag:
+        rows = await db.execute(
+            _RELEASE_BY_TAG,
+            {'project_id': project_id, 'tag': tag},
+            ['id'],
+        )
+        if rows:
+            return _ExistingRelease(
+                str(graph.parse_agtype(rows[0]['id'])), True
+            )
+    rows = await db.execute(
+        _RELEASE_BY_COMMITTISH,
+        {'project_id': project_id, 'committish': committish},
+        ['id'],
+    )
+    if rows:
+        return _ExistingRelease(str(graph.parse_agtype(rows[0]['id'])), False)
+    return None
+
+
+async def _adopt_release_tag(
+    db: graph.Graph,
+    *,
+    release_id: str,
+    tag: str,
+) -> None:
+    """Name an untagged release, leaving an already-tagged one alone."""
+    await db.execute(
+        _RELEASE_ADOPT_TAG,
+        {
+            'release_id': release_id,
+            'tag': tag,
+            'now': datetime.datetime.now(datetime.UTC).isoformat(),
+        },
+        ['id'],
+    )
+
+
 #: Alias kept for readers of this module; the map is shared with the
 #: sweeper, which folds the same plugin answers into the same statuses.
 _RUN_STATUS_TO_EVENT_STATUS = deployment_nodes.RUN_STATUS_TO_STATUS
@@ -588,12 +716,26 @@ async def _hydrate_release_train(
 # -- Endpoints ----------------------------------------------------------
 
 
-@releases_router.post('/', status_code=201, response_model=ReleaseResponse)
+@releases_router.post(
+    '/',
+    status_code=201,
+    response_model=ReleaseResponse,
+    responses={
+        200: {
+            'model': ReleaseResponse,
+            'description': (
+                'The release already existed; it is returned unchanged '
+                'rather than conflicting.'
+            ),
+        },
+    },
+)
 async def create_release(
     org_slug: str,
     project_id: str,
     data: ReleaseCreate,
     db: graph.Pool,
+    response: fastapi.Response,
     background_tasks: fastapi.BackgroundTasks,
     auth: typing.Annotated[
         permissions.AuthContext,
@@ -602,46 +744,64 @@ async def create_release(
         ),
     ],
 ) -> ReleaseResponse:
-    """Create a new release for a project."""
+    """Create a release for a project, or return the one that exists.
+
+    The call is idempotent: a release matching the body is returned with
+    ``200`` rather than conflicting, because more than one webhook can
+    announce the same release.  A ``deployment_status`` delivery and a
+    ``release`` delivery describe one artifact from two angles, and the
+    first to arrive must not make the second an error -- nor a second
+    node.  Only a first create answers ``201``.
+    """
     if not await _project_exists(db, org_slug, project_id):
         raise fastapi.HTTPException(
             status_code=404,
             detail=f'Project {project_id!r} not found',
         )
 
-    # Per-project uniqueness pre-check. A tag is the release's
-    # identity: it names one shippable artifact, and the commit it
-    # points at moves (the release workflow bumps the version, then
-    # tags the bump commit). Matching on the committish instead let the
-    # post-bump SHA miss the node Imbi had already created and create a
-    # duplicate. Only an untagged release falls back to the committish.
-    # AGE has no NULL equality, so nullable comparisons go through
-    # COALESCE to a sentinel.
-    existing_query: typing.LiteralString = """
-    MATCH (p:Project {{id: {project_id}}})-[:HAS_RELEASE]->(r:Release)
-    WHERE (COALESCE({tag}, '') <> '' AND r.tag = {tag})
-       OR (COALESCE({tag}, '') = ''
-           AND r.committish = {committish}
-           AND COALESCE(r.tag, '') = '')
-    RETURN r.id AS id
-    """
-    existing = await db.execute(
-        existing_query,
-        {
-            'project_id': project_id,
-            'committish': data.committish,
-            'tag': data.tag,
-        },
-        ['id'],
+    # Local import avoids a circular import: project_deployments imports
+    # append_deployment_event from this module.
+    from imbi.api.endpoints.project_deployments import (
+        fetch_release_notes_for_tag,
+        resolve_committish_for_tag,
     )
-    if existing:
-        raise fastapi.HTTPException(
-            status_code=409,
-            detail=(
-                f'Release tag={data.tag!r} committish={data.committish!r}'
-                f' already exists for project {project_id!r}'
-            ),
+
+    committish = data.committish
+    if committish is None:
+        # Guaranteed by ReleaseCreate.validate_identity.
+        assert data.tag is not None  # noqa: S101
+        committish = await resolve_committish_for_tag(
+            db,
+            org_slug=org_slug,
+            project_id=project_id,
+            tag=data.tag,
+            auth=auth,
         )
+        if committish is None:
+            raise fastapi.HTTPException(
+                status_code=422,
+                detail=(
+                    f'Could not resolve tag {data.tag!r} to a commit for'
+                    f' project {project_id!r}; supply committish explicitly'
+                ),
+            )
+
+    match = await _find_existing_release(
+        db, project_id=project_id, tag=data.tag, committish=committish
+    )
+    if match is not None:
+        # A tagged create that matched an untagged node adopts it: the
+        # deployment webhook records the commit before the release
+        # webhook names it, and leaving them apart is what produces the
+        # duplicate this endpoint exists to avoid.
+        if data.tag and not match.by_tag:
+            await _adopt_release_tag(db, release_id=match.id, tag=data.tag)
+        existing = await _fetch_release(db, org_slug, project_id, match.id)
+        if existing is not None:
+            response.status_code = 200
+            return _release_to_response(existing, project_id)
+        # Raced with a delete between the two reads; fall through and
+        # create the node rather than 404 a create.
 
     # Spec calls for ``auth.user.username``; the User model uses
     # ``email`` as the principal identity (no ``username`` field).
@@ -656,12 +816,6 @@ async def create_release(
     # and the release is still created (identified by committish + tag).
     description = data.description
     if data.tag and not description:
-        # Local import avoids a circular import: project_deployments
-        # imports append_deployment_event from this module.
-        from imbi.api.endpoints.project_deployments import (
-            fetch_release_notes_for_tag,
-        )
-
         description = await fetch_release_notes_for_tag(
             db,
             org_slug=org_slug,
@@ -673,7 +827,7 @@ async def create_release(
     props: dict[str, typing.Any] = {
         'id': nanoid.generate(),
         'tag': data.tag,
-        'committish': data.committish,
+        'committish': committish,
         'title': data.title,
         'description': description,
         'links': _serialize_links(data.links),

{imbi_api-2.32.2 → imbi_api-2.32.3}/tests/endpoints/test_project_deployments.py

@@ -6399,6 +6399,146 @@ class ResolveRemoteTagsTestCase(unittest.IsolatedAsyncioTestCase):
             await self._resolve(['1.0.0'])
 
 
+class ResolveCommittishForTagTestCase(unittest.IsolatedAsyncioTestCase):
+    """The tag lookup behind a tag-only release create.
+
+    ``create_release`` rejects the release with a 422 when this answers
+    ``None``, so the same absence-vs-failure distinction
+    ``resolve_remote_tags`` draws has to hold here: only a positive "no
+    such ref" may answer ``None``. A failure to reach the remote must
+    raise, or a timeout would read as an invalid tag.
+    """
+
+    def setUp(self) -> None:
+        self.resolve_committish = mock.AsyncMock(
+            return_value=mock.Mock(sha='9b2356a5da56631e3faf75bc5710bad1')
+        )
+        for target, replacement in (
+            ('_resolve_and_context', mock.AsyncMock()),
+            (
+                '_handler',
+                mock.Mock(
+                    return_value=mock.Mock(
+                        resolve_committish=self.resolve_committish
+                    )
+                ),
+            ),
+            ('_resolve_credentials', mock.Mock(return_value={})),
+            ('persist_link_writeback', mock.AsyncMock()),
+        ):
+            patcher = mock.patch(f'{_MODULE}.{target}', replacement)
+            self.addCleanup(patcher.stop)
+            patcher.start()
+        project_deployments._resolve_and_context.return_value = (
+            mock.Mock(plugin_slug='github'),
+            mock.Mock(environment_config=None),
+            {},
+        )
+
+    async def _resolve(self, tag: str = '5.0.2') -> str | None:
+        return await project_deployments.resolve_committish_for_tag(
+            mock.AsyncMock(),
+            org_slug='octo',
+            project_id='p1',
+            tag=tag,
+            auth=mock.Mock(),
+        )
+
+    async def test_resolves_the_tag_to_a_short_committish(self) -> None:
+        self.assertEqual('9b2356a', await self._resolve())
+
+    async def test_a_remote_404_answers_none(self) -> None:
+        self.resolve_committish.side_effect = _http_status_error(404)
+        self.assertIsNone(await self._resolve())
+
+    async def test_a_remote_422_answers_none(self) -> None:
+        self.resolve_committish.side_effect = _http_status_error(422)
+        self.assertIsNone(await self._resolve())
+
+    async def test_no_capability_answers_none(self) -> None:
+        project_deployments._resolve_and_context.side_effect = (
+            fastapi.HTTPException(status_code=404, detail='none')
+        )
+        self.assertIsNone(await self._resolve())
+
+    async def test_a_missing_credential_propagates_its_503(self) -> None:
+        # ``_resolve_and_context`` raises this deliberately, and its own
+        # comment calls a retry reasonable.  Reading it as an absent tag
+        # is the same mistake as swallowing the timeout, one call up.
+        project_deployments._resolve_and_context.side_effect = (
+            fastapi.HTTPException(
+                status_code=503,
+                detail={'error': 'no_service_credential'},
+            )
+        )
+        with self.assertRaises(fastapi.HTTPException) as ctx:
+            await self._resolve()
+        self.assertEqual(503, ctx.exception.status_code)
+
+    async def test_an_authorization_failure_propagates_its_403(self) -> None:
+        # The gateway posts as a service principal, so act-as-service
+        # checks are reachable here.  Not an answer about the tag.
+        project_deployments._resolve_and_context.side_effect = (
+            fastapi.HTTPException(status_code=403, detail='nope')
+        )
+        with self.assertRaises(fastapi.HTTPException) as ctx:
+            await self._resolve()
+        self.assertEqual(403, ctx.exception.status_code)
+
+    async def test_an_ambiguous_capability_propagates_its_400(self) -> None:
+        # "Multiple integrations provide this capability" is a config
+        # error to surface, not a tag that does not exist.
+        project_deployments._resolve_and_context.side_effect = (
+            fastapi.HTTPException(status_code=400, detail='ambiguous')
+        )
+        with self.assertRaises(fastapi.HTTPException) as ctx:
+            await self._resolve()
+        self.assertEqual(400, ctx.exception.status_code)
+
+    async def test_an_unimplemented_plugin_answers_none(self) -> None:
+        self.resolve_committish.side_effect = NotImplementedError
+        self.assertIsNone(await self._resolve())
+
+    async def test_a_remote_500_raises_503_rather_than_absence(self) -> None:
+        self.resolve_committish.side_effect = _http_status_error(500)
+        with self.assertRaises(fastapi.HTTPException) as ctx:
+            await self._resolve()
+        self.assertEqual(503, ctx.exception.status_code)
+
+    async def test_a_remote_403_raises_503_rather_than_absence(self) -> None:
+        # A revoked credential is not the tag failing to exist.
+        self.resolve_committish.side_effect = _http_status_error(403)
+        with self.assertRaises(fastapi.HTTPException) as ctx:
+            await self._resolve()
+        self.assertEqual(503, ctx.exception.status_code)
+
+    async def test_a_transport_failure_raises_503(self) -> None:
+        self.resolve_committish.side_effect = httpx.ConnectError('down')
+        with self.assertRaises(fastapi.HTTPException) as ctx:
+            await self._resolve()
+        self.assertEqual(503, ctx.exception.status_code)
+
+    async def test_a_timeout_keeps_its_503_and_retry_after(self) -> None:
+        # ``call_with_timeout`` raises this; swallowing it turned a
+        # "retry in 5s" into a terminal "your tag is invalid".
+        self.resolve_committish.side_effect = fastapi.HTTPException(
+            status_code=503,
+            detail='Plugin timed out',
+            headers={'Retry-After': '5'},
+        )
+        with self.assertRaises(fastapi.HTTPException) as ctx:
+            await self._resolve()
+        self.assertEqual(503, ctx.exception.status_code)
+        self.assertEqual({'Retry-After': '5'}, ctx.exception.headers)
+
+    async def test_rate_limiting_propagates(self) -> None:
+        self.resolve_committish.side_effect = plugin_errors.PluginRateLimited(
+            retry_at=1.0
+        )
+        with self.assertRaises(plugin_errors.PluginRateLimited):
+            await self._resolve()
+
+
 class IngestDriftNotesTests(ProjectDeploymentsTestCase):
     URL = '/organizations/myorg/projects/proj1/deployments/drift-notes'
     BODY: typing.ClassVar[dict[str, str]] = {