Repository navigation
Description
Summary
libtmux-java has no public way to start a private tmux server, so every API example runs inside examples/api/run.sh, a 99-line shell launcher. The program itself only receives the tmux executable, socket path and configuration file as three arguments. The published Java, Kotlin and Scala reference pages show that launcher above a few lines of library code, and the Clojure facade (#20) copies it.
Motivation
An example should show the library doing the work. Today the launcher does the part a reader most needs to see: it creates a private socket directory and an empty config, starts tmux, removes TMUX, TMUX_PANE and LIBTMUX_SOCKET* from the program's environment, stops the server on success or failure, and fails the run when a server leaks. examples/api/README.md states the split: "Each program receives the tmux executable, socket path, and configuration file as three arguments" and "the launcher owns server shutdown".
So a reader who copies an example gets a program that cannot run on its own, plus a shell script to copy beside it. The launcher spells out exactly the work libtmux exists to take off the caller.
The Ruby port does this in the library. LibTmux::Server.start "Starts a foreground daemon on a new private endpoint. Close owns its exit", with an empty config by default, and every Ruby example is one program:
LibTmux::Server.start do |server|
session = server.new_session(name: "demo", command: ["/bin/cat"])
endIn libtmux-java the only code that starts and owns a server is test code: libtmux-junit5's TmuxExtension and the NamedServerFixture the example style guide names.
Proposal
- Add a public entry point to
libtmuxthat starts a private tmux server, owned by the returned handle:- its own socket directory
- an empty config unless one is given
- none of the caller's
TMUX,TMUX_PANEorLIBTMUX_SOCKET* - on close, it stops the server and fails if the server is still answering
- Make it
AutoCloseablefor try-with-resources, and give the wrappers their idiomatic form:- Kotlin
use {} - Scala
Usingand a CatsResource - Clojure
with-openor awith-servermacro (Add native Clojure facade #20)
- Kotlin
- Rewrite the Java, Kotlin, Scala and Clojure API programs as self-contained programs that start their server through it, with no
run.shand no arguments passed from a script. Fixtures the programs need (thework-oneandwork-twosessions) are created by the program through the API. - Keep the leak check in the library's close, where the example executable tests can still assert it.
References
- The launcher was added in Examples(docs): Add complete API programs #48 and hardened in Sandbox: Keep test runs away from the developer's tmux server #123 (private
TMUX_TMPDIR,LIBTMUX_SOCKET*scrubbing, leak check). - Add a standalone, CI-run example program for each core capability #129 asks for standalone capability programs with their own server setup; this entry point is what lets them, and the API programs, drop the launcher.
- Published reference page with the launcher: https://libtmux.org/en/java/latest/reference/io-github-libtmux-server-server/
- The Clojure facade copies the launcher: Add native Clojure facade #20.
Activity
Server(feat[start]): Start a private tmux server
Junit5(refactor[extension]): Start fixtures with Server.start
Kotlin(feat[start]): Add Server.start and withPrivateServer
Scala(feat[start]): Add Server.start for Using and Resource
Examples(refactor[api]): Start each API program's server itself
Changelog(docs[start]): Record Server.start and the standalone examples
Clojure(feat[start]): Add start! for a private tmux server
Examples(refactor[clojure]): Start each Clojure program's server itself
Server(feat[start]): Start a private tmux server
Junit5(refactor[extension]): Start fixtures with Server.start
Kotlin(feat[start]): Add Server.start and withPrivateServer
Scala(feat[start]): Add Server.start for Using and Resource
Examples(refactor[api]): Start each API program's server itself
Changelog(docs[start]): Record Server.start and the standalone examples
8 remaining items
Clojure(feat[start]): Add start! for a private tmux server
Examples(refactor[clojure]): Start each Clojure program's server itself
Server(feat[start]): Start a private tmux server
Junit5(refactor[extension]): Start fixtures with Server.start
Kotlin(feat[start]): Add Server.start and withPrivateServer
Scala(feat[start]): Add Server.start for Using and Resource
Examples(refactor[api]): Start each API program's server itself
Changelog(docs[start]): Record Server.start and the standalone examples
Clojure(feat[start]): Add start! for a private tmux server
Examples(refactor[clojure]): Start each Clojure program's server itself
docs(readme[start]) Start the quick start's server with Server.start
Clojure(feat[start]): Add start! for a private tmux server
Examples(refactor[clojure]): Start each Clojure program's server itself
docs(readme[start]) Start the quick start's server with Server.start