Skip to content

feat: add Viaduct Development Server (devserve) with GraphiQL IDE #224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
fireboy1919 wants to merge 24 commits into
base: main
Choose a base branch
from
Open

feat: add Viaduct Development Server (devserve) with GraphiQL IDE #224

fireboy1919 wants to merge 24 commits into from

Conversation

@fireboy1919
Copy link
Collaborator

@fireboy1919 fireboy1919 commented Nov 14, 2025 •
edited
Loading

Summary

Adds a new development server feature (devserve) to Viaduct applications, providing a lightweight local development environment with GraphiQL IDE integration.

Key Features

1. Development Server (devserve task)

  • Ktor-based development server for Viaduct GraphQL applications
  • Automatic discovery and initialization of ViaductFactory instances
  • GraphiQL IDE accessible at /graphiql endpoint
  • Configurable host and port (supports port 0 for dynamic assignment)
  • Integrated with the viaduct.application Gradle plugin

2. Port Configuration

  • Default port: 8080
  • Configurable via -Pdevserve.port=<port>
  • Port 0 support for dynamic assignment (useful for testing)
  • Logs actual bound port after startup

3. GraphiQL Integration

  • Interactive GraphQL IDE with syntax highlighting and autocomplete
  • Automatic schema introspection
  • Query history and documentation explorer
  • Comprehensive logging of introspection queries
  • Supports maintenance - allows for upgrading the graphiql instance and applying the Viaduct customizations to it.

4. Factory Discovery

  • Automatic discovery of ViaductFactory implementations via @ViaductApplication annotation
  • Fallback to DefaultViaductFactory if no custom factory found
  • Support for both service-based and module-based applications

5. Publishing Configuration

  • Complete Maven publishing metadata
  • No mavenLocal dependency required
  • Dependency substitution for local development
  • Published to Maven Central for external users

Changes

New Modules

  • devserve/runtime: Core development server implementation
    • DevServeServer.kt: Main server with Ktor integration
    • FactoryDiscovery.kt: Automatic ViaductFactory discovery
    • DefaultViaductFactory.kt: Default factory implementation
    • GraphiQLHtml.kt: GraphiQL HTML generation
    • Comprehensive test coverage (20 tests)

Modified Files

  • gradle-plugins/application-plugin/src/main/kotlin/viaduct/gradle/ViaductApplicationPlugin.kt: Added devserve task
  • settings.gradle.kts: Added devserve:runtime module and dependency substitution
  • All demoapp settings.gradle.kts: Added dependency substitution for composite builds

Usage

# Start development server on default port (8080)
./gradlew :starwars:devserve

# Start on custom port
./gradlew :starwars:devserve -Pdevserve.port=3000

# Start on dynamic port (useful for testing)
./gradlew :starwars:devserve -Pdevserve.port=0

# Custom host
./gradlew :starwars:devserve -Pdevserve.host=localhost

Then open http://localhost:8080/graphiql to access the GraphiQL IDE.

Testing

All tests pass:

  • DevServeServerPortTest: Port configuration including port 0
  • IntrospectionTest: GraphQL introspection support verification
  • FactoryDiscoveryTest: ViaductFactory discovery and initialization
  • DefaultViaductFactoryTest: Default factory implementation
  • GraphiQLHtmlTest: GraphiQL HTML generation

Demo Apps

All four demo applications now support devserve:

  • ✅ cli-starter
  • ✅ jetty-starter
  • ✅ ktor-starter
  • ✅ starwars

Breaking Changes

None

🤖 Generated with Claude Code

skevy
skevy reviewed Nov 19, 2025
View reviewed changes
Rusty Phillips and others added 2 commits November 19, 2025 10:47
Refactor devserve implementation and terminology
a4e0e7b 
- Changed 'hot-reloading' to 'auto-reloading' throughout documentation and code
- Replaced manual ProcessBuilder with Gradle's javaExec task in ViaductApplicationPlugin
- Fixed configuration cache issue in devserve module by using Delete task configuration directly
@claude
fix(devserve): resolve INCLUDED version and Gradle 9.x compatibility …
ee8d756 
…issues

- Add versionMapping to devserve publishing to resolve actual versions
  instead of "INCLUDED" placeholder in published POM
- Migrate from deprecated project.javaexec to ExecOperations.javaexec
  for Gradle 9.x compatibility

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
@fireboy1919 fireboy1919 changed the title Add Viaduct Development Server (devserve) with GraphiQL IDE feat: add Viaduct Development Server (devserve) with GraphiQL IDE Dec 1, 2025
Rusty Phillips and others added 3 commits December 1, 2025 09:03
@claude
fix: restore and configure coverage verification task
9114cb9 
The testCodeCoverageVerification task was lost during merge and lacked
proper configuration. This restores it with proper executionData,
classDirectories, and sourceDirectories from the aggregated report.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
refactor(api): rename @ViaductApplication to @ViaductConfiguration
6be21d3 
Rename the annotation used to mark ViaductFactory implementations for
automatic discovery from @ViaductApplication to @ViaductConfiguration
for better clarity about its purpose.
feat(devserve): add ViaductDevServeProvider for all demo apps
836c93e 
Introduces the @ViaductDevServeConfiguration annotation and
ViaductDevServeProvider interface to allow demo apps to provide
their Viaduct instance to DevServe via their DI framework.

- Add ViaductDevServeProvider interface and annotation
- Add DevServe providers for cli-starter, jetty-starter, ktor-starter
- Add StarWarsDevServeProvider for Micronaut-based starwars app
- Update demo apps to use shared ViaductConfiguration singletons
- Both production and devserve now share the same Viaduct instance
@fireboy1919 fireboy1919 force-pushed the add_devserv_mode branch 2 times, most recently from f8a8deb to c61ed86 Compare December 3, 2025 15:16
Rusty Phillips added 5 commits December 5, 2025 15:33
refactor(devserve): use GraphiQL from service-wiring module
eca262b 
Remove duplicated GraphiQL resources and generator from devserve.
Instead, delegate to the GraphiQL HTML provided by the service-wiring
module which now owns these resources.

- Remove buildSrc GraphiQLHtmlCustomizer
- Remove devserve graphiql resources (js files)
- Remove downloadGraphiQLHtml task from devserve build
- Update GraphiQLHtml.kt to delegate to service-wiring
refactor(starwars): remove devserve integration
74be977 
Revert starwars demo app to use its original GraphiQL setup.
DevServe will only be tested in helloworld and ktor starter apps.
refactor: rename devserve to serve throughout codebase
4948594 
Rename DevServe to Viaduct Server since it may be used in production.

- Rename devserve/ directory to serve/
- Rename DevServeServer class to ViaductServer
- Rename ViaductDevServeConfiguration to ViaductServerConfiguration
- Rename ViaductDevServeProvider to ViaductServerProvider
- Update package names from viaduct.devserve to viaduct.serve
- Update all demo app provider classes
- Update docs and settings files
refactor(serve): make DefaultViaductFactory internal with automatic f…
7ad5fdd 
…allback

- Make DefaultViaductFactory internal (not part of public API)
- Remove constructor parameters (no longer accepts packagePrefix)
- Use DefaultViaductFactory as automatic fallback when no
  @ViaductServerConfiguration is found (instead of throwing error)
- Add INFO logs explaining zero-arg constructor limitation
- Update FactoryDiscovery to return DefaultViaductFactory for empty case
- Update tests to reflect new behavior
feat(service-wiring): add GraphiQL HTML resources with Viaduct custom…
5a5d9f7 
…izations

Cherry-picked from move-graphiql-generator branch to support serve module.

Adds:
- Generated GraphiQL HTML with Viaduct customizations
- introspection-patch.js: Fixes GraphQL Java compatibility with GraphiQL 5
- global-id-plugin.jsx: Global ID encode/decode plugin
- jsx-loader.js: Runtime JSX transpilation
- GraphiQLHtmlCustomizer for regenerating HTML
test(serve): add JS file serving test and improve resource loading
5857baa 
- Add test to verify JS files (jsx-loader.js, introspection-patch.js,
  global-id-plugin.jsx) are served from service-wiring resources
- Improve resource loading to use multiple classloader strategies:
  thread context classloader first, then class's own classloader
- This ensures resources from service-wiring are found reliably
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@skevy skevy skevy left review comments

@kristileka kristileka Awaiting requested review from kristileka

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@fireboy1919 @skevy