GuacLite.pm untested

filter: Statementstmt 0.0% 0 / 5 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 1 Podpod n/a totaltotal 0.0% 0 / 6 CC 1 SCAR 6.9
CC
1
Cov
0%
BEGIN
2.0
CRAP 2.0
1 package GuacLite;
2  
3 use strict;
4  
5 our $VERSION = '0.02';
6 $VERSION = eval $VERSION;
7  
8 1;
9  
10 =head1 NAME
11  
12 GuacLite - Toolkit for implementing a frontend server/client the Apache Guacamole system
13  
14 =head1 DESCRIPTION
15  
16 =head1 GUACAMOLE SYSTEM OVERVIEW
17  
18 The L<Apache Guacamole system|https://guacamole.apache.org/> comprises several tools which used in combination can provide access to remote hosts via various protocols.
19  
20 The first component is a daemon, "Guacd", which is a compiled application that uses these various protocols to communicate with host computers.
21 It then accepts inbound connections from clients which speak a unified protocol, called guacamole, to access those hosts.
22 Guacd is therefore both a proxy/relay and a translator.
23  
24 In theory any system could connect to guacd but in practice there is a major client, the Java application called "guacamole-common".
25 It is a server which serves a Javascript application and provides a websocket <-> tcp proxy/relay between the javascript application and guacd.
26 It also has user, group, and host management, authentication, and policy management.
27  
28 Because of these extra features it requires persistence (a database) and api calls to add/update users and hosts in order to use it.
29 Also, because it is written in Java any extension to the system must also be written in Java and served alongside it in a Tomcat or other JSP server.
30  
31 The Javascript application, called "guacamole-common-js", is a browser-native client for guacd with the exception that it speaks websocket rather than direct tcp.
32 Therefore it requires a service that can provide that relay.
33 It also sends keep-alive (ping/pong) messages that don't conform to the guacamole protocol and that the proxy must filter out and reply to.
34  
35 =head1 MOTIVATION AND COMPONENTS
36  
37 This project exists to allow non-Java projects that wish to use guacamole-common-js to access a guacd service, without having to conform to the usage expectations of guacamole-common, and without having to alter that application via Java.
38 It provides a toolkit for implementing a frontend server/client to guacd via Perl and Mojolicious, without any built-in business logic (user management, host configuration).
39 It provides the following components, each of which are independent and may be used with any Mojolicious application to provide or embed remote access via a guacd service.
40  
41 =head2 Guacd Client
42  
43 L<GuacLite::Client::Guacd> is a Perl/L<Mojolicious> client that communicates with a guacd service.
44 It configures all relevant parameters for communicating with the guacd service and opening a connection to the remote host (including performing the requisite handshake).
45  
46 The current supported version of the protocol is 1.3.0
47  
48 =head2 Guacd Websocket Tunneling Plugin
49  
50 L<GuacLite::Plugin::Guacd> is a plugin that provides a helper method to establish a websocket connection between a client and a guacd service via a configured (but not connected) L<GuacLite::Client::Guacd> instance.
51 It initiates the guacd connection and triggers the handshake, it then passes messages between the guacd connection and the client's websocket, monitoring backpressure between them, and handling the keep-alive messages.
52  
53 In the future, passing a connected guacd client should be possible, but it hasn't been implemented yet.
54  
55 =head2 Utilities
56  
57 L<GuacLite::Util> provides utilies for using the system.
58 Currently it only provides one function which can bundle the guacamole-common-js files into a single javascript file and provide an initialize function to defer loading the javascript until necessary, which is required by some newer browsers.
59  
60 =head2 Example Web Application
61  
62 L<GuacLite::Client::Web> is an example web application which is intended to be used as a reference and test implementation of the tools.
63 It should function correctly but currently has almost no user interface and for the time being shouldn't be relied on to be in its current state.
64 While the preceding libraries in the distribution are considered production ready and will only change if necessary, this example application can and may change without warning.
65  
66 In the future, perhaps this application will be made into a fully featured web client, however that risks falling into the (my opinion) feature creep seen in the original Java application that it replaces.
67  
68 =head2 guaclite script
69  
70 It includes an script which can start the example application or can be used to bundle the javascript via the utility function.
71 See details of both above.
72  
73 =head2 Bundled Assets
74  
75 The distribution does include the bundled version guacamole-common-js.
76 The exact version provided is not guaranteed.
77 For production environments, it is encouraged that you download you own copy of the library and either bundle it with the utility or else bundle as you see fit.
78  
79 It also contains the templates/files for the example application, which are subject to the caveats of the example application itself.
80  
81 =head2 Containerization Files
82  
83 The distribution contains example Dockerfile and docker-compose.yml files to facilitate easy use of the example application and for deploying both it and a guacd service.
84 These are provided as reference only and should not be relied upon for production use, owing to the same warning as previously about the stability of the example application.
85  
86 =head1 AUTHOR
87  
88 Joel Berger, <joel.a.berger@gmail.com>
89  
90 =head1 CONTRIBUTORS
91  
92 None yet :)
93  
94 =head1 COPYRIGHT AND LICENSE
95  
96 This original work is copyright 2020 - 2021 by L</AUTHOR> and L</CONTRIBUTORS>.
97  
98 This original work is licensed under the Apache License, Version 2.0 (the "License");
99 you may not use this file except in compliance with the License.
100 You may obtain a copy of the License at
101  
102 http://www.apache.org/licenses/LICENSE-2.0
103  
104 Unless required by applicable law or agreed to in writing, software
105 distributed under the License is distributed on an "AS IS" BASIS,
106 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
107 See the License for the specific language governing permissions and
108 limitations under the License.
109  
110 =head1 LICENSE NOTICE FOR BUNDLED WORKS
111  
112 This repository and/or library also bundles work from L<"Apache Guacamole"|https://guacamole.apache.org/>
113 which is also licensed under the terms of the Apache 2.0 License.