Transform any Go program into a client of itself, remotely or locally.
+Use, manage teamservers and clients with code, with their CLI, or both.
++ + + + + + + + + + + + + + + + + + + + + + + +
+ + +----- +## Summary + +The client-server paradigm is an ubiquitous concept in computer science. Equally large and common is +the problem of building software that _collaborates_ easily with other peer programs. Although +writing collaborative software seems to be the daily task of many engineers around the world, +succeedingly and easily doing so in big programs as well as in smaller ones is not more easily done +than said. Difficulty still increases -and keeping in mind that humans use software and not the +inverse- when programs must enhance the capacity of humans to collaborate while not restricting the +number of ways they can do so, for small tasks as well as for complex ones. + +The `reeflective/team` library provides a small toolset for arbitrary programs (and especially those +controlled in more or less interactive ways) to collaborate together by acting as clients and +servers of each others, as part of a team. Teams being made of players (humans _and_ their tools), +the library focuses on offering a toolset for "human teaming": that is, treating software tools that +are either _teamclients_ or _teamservers_ of others, within a defined -generally restricted- team of +users, which shall generally be strictly and securely authenticated. + +The project originates from the refactoring of a security-oriented tool that used this approach to +clearly segregate client and server binary code (the former's not needing most of the latter's). +Besides, the large exposure of the said-tool to the CLI prompted the author of the +`reeflective/team` library to rethink how the notion of "collaborative programs" could be approached +and explored from different viewpoints: distinguishing between the tools' developers, and their +users. After having to reuse this core code for other projects, the idea appeared to extract the +relevant parts and to restructure and repackage them behind coherent interfaces (API and CLI). + + +----- +## Components & Terms + +The result consists in 2 Go packages (`client` and `server`) for programs needing to act as: +- A **Team client**: a program, or one of its components, that needs to rely on a "remote" program peer + to serve some functionality that is available to a team of users' tools. The program acting as a + _teamclient_ may do so for things as simple as sending a message to the team, or as complicated as a + compiler backend with which multiple client programs can send data to process and build. +- A **Team server**: The remote, server-side counterpart of the software teamclient. Again, the + teamserver can be doing anything, from simply notifying users' teamclient connections to all the team + all the way to handling very complex and resource-hungry tasks that can only be ran on a server host. + +Throughout this library and its documentation, various words are repeatedly employed: +- _teamclient_ refers to either the client-specific toolset provided by this library + (`team/client.Client` core type) or the software making use of this teamclient code. +- _teamserver_ refers to either the server-specific toolset provided to make a program serve its + functionality remotely, or to the tools embedding this code in order to do so. +- _team tool/s_ might be used to refer to programs using either or all of the library components at + large. + +----- +## Principles, Constraints & Features + +The library rests on several principles, constraints and ideas to fulfill its intended purpose: +- The library's sole aim is to **make most programs able to collaborate together** under the + paradigm of team clients and team servers, and to do so while ensuring performance, coherence, + ease of use and security of all processes and workflows involved. This, under the _separate + viewpoints_ of tool development, enhancement and usage. +- Ensure a **working-by-default toolset**, assuming that the time spent on any tool's configuration + is inversely proportional to its usage. Emphasis on this aspect should apply equally well to team + tools' users and developers. +- Ensure the **full, secure and reliable authentication of all team clients and servers' + interactions**, by using certificate-based communication encryption and user authentication, _aka_ + "zero-trust" model. Related and equally important, ensure the various team toolset interfaces + provide for easy and secure usage of their host tools. +- **Accomodate for the needs of developers to use more specific components**, at times or at points, + while not hampering on the working-by-default aspects of the team client/server toolset. Examples + include replacing parts or all of the transport, RPC, loggers, database and filesystem + backends. +- To that effect, the library offers **different interfaces to its functionality**: an API (Go code) + provides developers a working-by-default, simple and powerful way to instruct their software how + to collaborate with peers, and a CLI, for users to operate their team tools, manage their related + team configurations with ease, with a featured command-line tree to embed anywhere. +- Ensure that team client/server functionality can be **easily integrated in automated workflows**: + this is done by offering clear code/execution paths and behaviors, for both users and developers, + and by providing commands and functions to ease deployment of said tools. + +----- +## CLI (Users) + +The following extracts assume a program binary named `teamserver`, which is simply the root command +of the server-side team code. In this case therefore, the binary program only purpose its to be a +teamserver, with no application-specific logic, (and is therefore quite useless on its own): +``` +$ teamserver +Manage the application server-side teamserver and users + +Usage: + teamserver [command] + +teamserver control + client Client-only teamserver commands (import configs, show users, etc) + close Close a listener and remove it from persistent ones if it's one + daemon Start the teamserver in daemon mode (blocking) + listen Start a teamserver listener (non-blocking) + status Show the status of the teamserver (listeners, configurations, health...) + systemd Print a systemd unit file for the application teamserver, with options + +user management + delete Remove a user from the teamserver, and revoke all its current tokens + export Export a Certificate Authority file containing the teamserver users + import Import a certificate Authority file containing teamserver users + user Create a user for this teamserver and generate its client configuration file +``` + +In this example, this program comes with a client-only binary counterpart, `teamclient`. The latter +does not include any team server-specific code, and has therefore a much smaller command set: +``` +$ teamclient +Client-only teamserver commands (import configs, show users, etc) + +Usage: + teamclient [command] + +Available Commands: + import Import a teamserver client configuration file for teamserver + users Display a table of teamserver users and their status + version Print teamserver client version +``` + +With these example binaries at hand, below are some examples of workflows. +Starting with the `teamserver` binary (which might be under access/control of a team admin): +``` bash +# 1 - Generate a user for a local teamserver, and import users from a file. +teamserver user --name Michael --host localhost +teamserver import ~/.other_app/teamserver/certs/other_app_user-ca-cert.teamserver.pem + +# 2 - Start some teamserver listeners, then start the teamserver daemon (blocking). +# Use the application-defined default port in the first call, and instruct the server +# to start the listeners automatically when used in daemon mode with --persistent. +teamserver listen --host localhost --persistent +teamserver listen --host 172.10.0.10 --port 32333 --persistent +teamserver status # Prints the saved listeners, configured loggers, databases, etc. +teamserver daemon --host localhost --port 31337 # Blocking: serves all persistent listeners and a main one at localhost:31337 + +# 3 - Export and enable a systemd service configuration for the teamserver. +teamserver systemd # Use default host, port and listener stacks. +teamserver systemd --host localhost --binpath /path/to/teamserver # Specify binary path. +teamserver systemd --user --save ~/teamserver.service # Print to file instead of stdout. + +# 4 - Import the "remote" administrator configuration for (1), and use it. +teamserver client import ~/Michael_localhost.teamclient.cfg +teamserver client version # Print the client and the server version information. +teamserver client users # Print all users registered to the teamserver and their status. + +# 5 - Quality of life +teamserver _carapace