refactor(plugins): decouple plugin framework from gateway observability service by crivetimihai · Pull Request #3140 · IBM/mcp-context-forge

crivetimihai · 2026-02-24T09:18:44Z

Note: This PR was re-created from #2827 due to repository maintenance. Your code and branch are intact. @araujof please verify everything looks good.

Description

Removes the plugin framework's direct dependency on mcpgateway.db.SessionLocal and mcpgateway.services.observability_service by introducing a protocol-based observability abstraction with dependency injection.

Closes: #2828

Problem

The plugin framework's _execute_with_timeout method imported SessionLocal and ObservabilityService directly from the gateway, creating a tight coupling that prevented the framework from operating standalone. This also required the plugin framework to manage database sessions for tracing — a concern that belongs to the host application.

Solution

Introduced ObservabilityProvider protocol and NullObservability no-op default in a new observability.py module
Added a current_trace_id ContextVar owned by the plugin framework (replacing the one imported from the gateway's observability service)
PluginExecutor and PluginManager now accept an optional observability parameter via constructor injection
get_plugin_manager() forwards the observability provider to the manager
The host application (mcpgateway) can inject its own implementation at startup; the framework operates without tracing when none is provided

Dependency direction (before → after)

# Before: circular
plugin framework ──imports──> mcpgateway.db, mcpgateway.services.observability_service

# After: clean inversion
mcpgateway ──injects──> plugin framework (ObservabilityProvider)

Changes

File	Change
`mcpgateway/plugins/framework/observability.py`	New — `ObservabilityProvider` protocol, `NullObservability` default, `current_trace_id` ContextVar
`mcpgateway/plugins/framework/manager.py`	`PluginExecutor` and `PluginManager` accept `observability` param; `_execute_with_timeout` uses injected provider instead of direct gateway imports
`mcpgateway/plugins/framework/__init__.py`	`get_plugin_manager()` accepts `observability` param; `ObservabilityProvider` added to `__all__`
`tests/unit/.../test_observability.py`	New — 5 tests: DI injection with tracing, no trace_id, no provider, NullObservability, executor injection
`tests/unit/.../test_manager_coverage.py`	Updated `TestExecuteWithTimeout` to test against injected provider instead of mocking `mcpgateway.db`/`mcpgateway.services`

Additional Changes

A few tests in tests/unit/../test_http_auth_integration.py were failing on dev environment when running the coverage target. Solution: Reset Starlette's cached middleware_stack after injecting the mock plugin manager so the middleware chain is rebuilt with the mock, and restore it afterward to avoid side effects on other tests.

Test plan

All unit tests pass
All doctests pass
New observability tests verify: span creation/completion with injected provider, graceful no-op without trace_id, graceful no-op without provider, provider failure fallback

…ion for observability service Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

- Eliminate double plugin execution on failure by restructuring _execute_with_timeout to separate observability from plugin execution - Close orphaned spans with status="error" when plugin hooks raise - Fix docstring typo in ObservabilityMiddleware - Move ObservabilityServiceAdapter import inside conditional block - Document ContextVar bridge requirement on both definitions Signed-off-by: Jonathan Springer <jps@s390x.com>

Cover error and edge-case paths in plugin executor observability spans and get_plugin_manager initialization with plugins enabled. Signed-off-by: Jonathan Springer <jps@s390x.com>

jonpspri

Clean refactor — protocol-based DI correctly decouples plugin framework from gateway observability internals, and fixes the latent double-execution bug in the old catch-all fallback. Session lifecycle, Borg singleton interaction, and ContextVar bridge are all sound. Test coverage is thorough.

Minor suggestions (non-blocking):

Consider exporting or removing NullObservability (currently dead code in production).
A defensive if self.observability: guard before end_span in the error/success paths of _execute_with_timeout would make the null-safety explicit rather than relying on the surrounding except.
The duplicated try/except/finally session boilerplate in the adapter could be collapsed into a helper.

…ty service (#3140) * refactor(plugins/framework): introduce protocol and dependency injection for observability service Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com> * chore: fix lint issues Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com> * feat: add observability adapter for plugins Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com> * tests: coverage gaps Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com> * fix: address review findings in observability refactor - Eliminate double plugin execution on failure by restructuring _execute_with_timeout to separate observability from plugin execution - Close orphaned spans with status="error" when plugin hooks raise - Fix docstring typo in ObservabilityMiddleware - Move ObservabilityServiceAdapter import inside conditional block - Document ContextVar bridge requirement on both definitions Signed-off-by: Jonathan Springer <jps@s390x.com> * tests: achieve 100% diff coverage for observability refactor Cover error and edge-case paths in plugin executor observability spans and get_plugin_manager initialization with plugins enabled. Signed-off-by: Jonathan Springer <jps@s390x.com> --------- Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com> Signed-off-by: Jonathan Springer <jps@s390x.com> Co-authored-by: Frederico Araujo <frederico.araujo@ibm.com> Co-authored-by: Jonathan Springer <jps@s390x.com>

crivetimihai requested review from kevalmahajan and madhav165 as code owners February 24, 2026 09:18

crivetimihai added this to the Release 1.0.0-GA milestone Feb 24, 2026

crivetimihai added enhancement New feature or request plugins SHOULD P2: Important but not vital; high-value items that are not crucial for the immediate release labels Feb 24, 2026

crivetimihai mentioned this pull request Feb 24, 2026

refactor(plugins): decouple plugin framework from gateway observability service #2827

Closed

3 tasks

araujof and others added 6 commits February 24, 2026 14:41

refactor(plugins/framework): introduce protocol and dependency inject…

d52fd6b

…ion for observability service Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

chore: fix lint issues

b9f8dd4

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

feat: add observability adapter for plugins

97fe4c2

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

tests: coverage gaps

8e5f775

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

tests: achieve 100% diff coverage for observability refactor

dde843a

Cover error and edge-case paths in plugin executor observability spans and get_plugin_manager initialization with plugins enabled. Signed-off-by: Jonathan Springer <jps@s390x.com>

jonpspri force-pushed the refactor/plugins_observability branch from 7c64397 to dde843a Compare February 24, 2026 14:43

jonpspri approved these changes Feb 24, 2026

View reviewed changes

jonpspri merged commit 6000884 into main Feb 24, 2026
6 of 49 checks passed

jonpspri deleted the refactor/plugins_observability branch February 24, 2026 20:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(plugins): decouple plugin framework from gateway observability service#3140

refactor(plugins): decouple plugin framework from gateway observability service#3140
jonpspri merged 6 commits intomainfrom
refactor/plugins_observability

crivetimihai commented Feb 24, 2026

Uh oh!

jonpspri left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

crivetimihai commented Feb 24, 2026

Description

Problem

Solution

Dependency direction (before → after)

Changes

Additional Changes

Test plan

Uh oh!

jonpspri left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants