Skip to content

No API starts a private tmux server, so examples need run.sh #142

Closed

Description

@tony

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"])
end

In 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 libtmux that 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_PANE or LIBTMUX_SOCKET*
    • on close, it stops the server and fails if the server is still answering
  • Make it AutoCloseable for try-with-resources, and give the wrappers their idiomatic form:
  • Rewrite the Java, Kotlin, Scala and Clojure API programs as self-contained programs that start their server through it, with no run.sh and no arguments passed from a script. Fixtures the programs need (the work-one and work-two sessions) 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

Activity

  1. 8 remaining items

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions