UI5 CLI v5 - Discuss Public Server API

[RandomByte]

UI5 CLI v5 has seen some major refactoring of the @ui5/server package, which now watches the file system and builds projects incrementally, rather than serving raw sources with minor on-the-fly modification. This added a bunch of new modules and APIs to the package, some of which are relevant for consumers that interface directly with the package (rather than using the UI5 CLI command). Here we want to discuss which APIs should become public, in order to support common use cases.

This is mainly intended for team internal discussions. But anyone who's interested, or has a relevant use case, is welcome to chime in.

AI generated overview of the current state of new APIs:

1. graph.serve() has no @public JSDoc

ProjectGraph.serve() has no doc comment at all. The sibling graph.build() directly above it is fully documented and @public, so it appears in the API Reference while serve() does not.

The documented Node.js examples call graphFromPackageDependencies and hand the graph to @ui5/server's serve / serveMiddleware, so they don't go through graph.serve() directly. But graph.serve() returns the BuildServer (with its public reader methods), so if that is meant to be a supported entry point it needs a @public doc block with its options and return type.

To be discussed: is graph.serve() intended as public API, or is @ui5/server the only sanctioned entry point?

2. BuildServer class has no JSDoc module/class header

BuildServer carries @public on individual reader methods:

• getReader()
• getRootReader()
• getDependenciesReader()

But the class itself has no @public / @class header, unlike server.js which declares @public @module @ui5/server. A consumer who obtains a BuildServer (from graph.serve() or from the buildServer returned by serveMiddleware) has no reference page for the class.

Depends on the outcome of gap 1: if graph.serve() and the returned BuildServer are public, the class needs a documented header.

3. Live re-resolution is not reachable through the public API

The serve() signature accepts graphFactory and projectWatcher. Together they enable the "Project Definition Changes" behavior: watch ui5.yaml / package.json / workspace config / --config / --dependency-definition, re-resolve the graph, and re-create the serving stack behind the stable HTTP server.

The CLI wires this up in serve.js:

const projectWatcher = await import("@ui5/project/internal/graph/ProjectDefinitionWatcher");
const {h2, port: actualPort} = await serverServe(graph, serverConfig, onError, buildGraph, projectWatcher);

projectWatcher comes from the internal subpath @ui5/project/internal/graph/ProjectDefinitionWatcher. An external consumer calling serve() without it gets a static server with no config-change re-resolution, so the definition-watching behavior only works via ui5 serve.

The injection exists because @ui5/server does not depend on @ui5/project; the owner (the CLI) threads the watcher in. Options to discuss for making the capability reachable to embedders:

• Promote the ProjectDefinitionWatcher subpath to a public export, and document the graphFactory + projectWatcher params of serve().
• Have @ui5/server depend on @ui5/project directly and construct the watcher itself, dropping the injection.
• Keep it CLI-only and document that embedders get a static server.

[matz3]

My thoughts here:

To be discussed: is graph.serve() intended as public API, or is @ui5/server the only sanctioned entry point?

Although the @ui5/server relies on that private API contract, I would rather keep it private for now, so that we can still rework the parameters if needed. But otherwise I see that some specific use cases could benefit from that API.

I would suggest that we add a comment to ProjectGraph#serve that it is being used by @ui5/server, so we do not forget to update both places in case we make changes.

2. BuildServer class has no JSDoc module/class header

I would question whether consumers of serveMiddleware really need the BuildServer interface, and rather keep it private (i.e. not return it), until both, our API contract is stable, and we know more about the use cases so we can make sure it fits.

[matz3]

My thoughts here:

To be discussed: is graph.serve() intended as public API, or is @ui5/server the only sanctioned entry point?

Although the @ui5/server relies on that private API contract, I would rather keep it private for now, so that we can still rework the parameters if needed. But otherwise I see that some specific use cases could benefit from that API.

I would suggest that we add a comment to ProjectGraph#serve that it is being used by @ui5/server, so we do not forget to update both places in case we make changes.

2. BuildServer class has no JSDoc module/class header

I would question whether consumers of serveMiddleware really need the BuildServer interface, and rather keep it private (i.e. not return it), until both, our API contract is stable, and we know more about the use cases so we can make sure it fits.

We agreed on the above plan and made the adjustments via #1520.

[matz3]

The new serveMiddleware API has been released via v5.0.0-alpha.8 🎉