Skip to content

Conversation

@Zsailer
Copy link
Collaborator

@Zsailer Zsailer commented Oct 23, 2025

Overview

This PR replaces the custom kernel client implementation in jupyter-server-documents with nextgen-kernels-api, a more extensive and reusable implementation of the Jupyter kernel protocol.

Key Changes

  • Removed ~1,700 lines of custom kernel code (kernels/ directory and associated tests)
  • Added dependency on nextgen-kernels-api >= 0.6.0
  • Simplified configuration using traitlets instead of custom subclasses
  • Improved message routing with filtering to exclude output messages from websocket clients while routing them to the output processor

Why nextgen-kernels-api?

The nextgen-kernels-api library aims to provide a robust, well-tested kernel client implementation that:

  1. Decouples kernel API improvements from server-side documents - The long-needed improvements to Jupyter Server's kernel API can evolve independently while jupyter-server-documents depends on a stable interface
  2. Enables code reuse - Other projects beyond jupyter-server-documents can leverage the same kernel client implementation
  3. Reduces maintenance burden - By using upstream code, we eliminate duplicate implementations and testing

There's an open discussion about moving nextgen-kernels-api into the jupyter-ai-contrib org: https://github.com/orgs/jupyter-ai-contrib/discussions/5

Technical Details

The PR:

  • Configures MultiKernelManager and KernelManager via traitlets to use DocumentAwareKernelClient
  • Uses message type filtering (msg_types, exclude_msg_types) to route messages efficiently
  • Maintains all existing functionality for real-time collaboration, output processing, and awareness updates
  • Preserves cell execution state tracking and document synchronization

Testing

All existing tests pass. The custom kernel tests were removed as they tested implementation details now handled by nextgen-kernels-api.


Diff stats: 24 files changed, 294 insertions(+), 1981 deletions(-)

@Zsailer Zsailer force-pushed the nextgen-kernels-api branch from 4b82d0c to 01217ca Compare October 23, 2025 23:00
@Zsailer Zsailer added the enhancement New feature or request label Oct 23, 2025
@Zsailer
Copy link
Collaborator Author

Zsailer commented Oct 24, 2025

The integration test failure is unrelated. I'm seeing this in other places as well. It looks like an error with transitive dependencies in other places in the JupyterLab stack.

@dlqqq
Copy link
Collaborator

dlqqq commented Oct 24, 2025

@Zsailer See #169. I was able to find a workaround to the integration test failures that are affecting our projects.

Replace custom kernel management implementation with nextgen-kernels-api.
Use message filtering to route outputs to processor while excluding them
from websocket clients. Configure kernel client via traitlets instead of
subclassing.
@Zsailer Zsailer force-pushed the nextgen-kernels-api branch from be7cb49 to 3b7dabc Compare October 30, 2025 04:38
Override get_session() to verify and restore yroom-to-kernel-client connections.
This is critical for persistent/remote kernels that survive server restarts, where
the in-memory yroom connection may be lost even though the session and kernel remain valid.

- Add _ensure_yroom_connected() method to handle connection logic
- Make connection verification idempotent to avoid duplicate connections
- Handle edge cases gracefully with logging but no exceptions
- Improves reliability when reconnecting to persistent kernel sessions
…ection logic

Tests cover:
- Cached room_id usage and reconstruction from database
- Non-notebook session handling
- Idempotency (avoiding duplicate connections)
- Edge cases (missing yrooms, sessions without kernels)
- get_session() integration with _ensure_yroom_connected()

These tests verify the critical functionality for maintaining yroom-kernel
connections for persistent kernels across server restarts.
Fixed issues with test fixture mocking:
- Use LoggingConfigurable parent class for proper traitlets compatibility
- Mock parent class's get_session method instead of YDocSessionManager's
- Make kernel_client.add_yroom an AsyncMock for proper async behavior

All 9 tests now pass successfully.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants