GUACAMOLE-44: Implement REST endpoint for listing tunnels and retrieving related data.

guacamole/src/main/java/org/apache/guacamole/rest/RESTServiceModule.java

@@ -37,6 +37,7 @@ import org.apache.guacamole.rest.history.HistoryRESTService;
 import org.apache.guacamole.rest.language.LanguageRESTService;
 import org.apache.guacamole.rest.patch.PatchRESTService;
 import org.apache.guacamole.rest.schema.SchemaRESTService;
+import org.apache.guacamole.rest.tunnel.TunnelRESTService;
 import org.apache.guacamole.rest.user.UserRESTService;
 
 /**
@@ -92,6 +93,7 @@ public class RESTServiceModule extends ServletModule {
         bind(PatchRESTService.class);
         bind(SchemaRESTService.class);
         bind(TokenRESTService.class);
+        bind(TunnelRESTService.class);
         bind(UserRESTService.class);
 
         // Set up the servlet and JSON mappings

guacamole/src/main/java/org/apache/guacamole/rest/tunnel/TunnelRESTService.java

@@ -0,0 +1,150 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.guacamole.rest.tunnel;
+
+import com.google.inject.Inject;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.util.Map;
+import java.util.Set;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DefaultValue;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.StreamingOutput;
+import org.apache.guacamole.GuacamoleException;
+import org.apache.guacamole.GuacamoleResourceNotFoundException;
+import org.apache.guacamole.GuacamoleSession;
+import org.apache.guacamole.rest.auth.AuthenticationService;
+import org.apache.guacamole.tunnel.StreamInterceptingTunnel;
+
+/**
+ * A REST Service for retrieving and managing the tunnels of active
+ * connections, including any associated objects.
+ *
+ * @author Michael Jumper
+ */
+@Path("/tunnels")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class TunnelRESTService {
+
+    /**
+     * The media type to send as the content type of stream contents if no
+     * other media type is specified.
+     */
+    private static final String DEFAULT_MEDIA_TYPE = "application/octet-stream";
+
+    /**
+     * A service for authenticating users from auth tokens.
+     */
+    @Inject
+    private AuthenticationService authenticationService;
+
+    /**
+     * Returns the UUIDs of all currently-active tunnels associated with the
+     * session identified by the given auth token.
+     *
+     * @param authToken
+     *     The authentication token that is used to authenticate the user
+     *     performing the operation.
+     *
+     * @return
+     *     A set containing the UUIDs of all currently-active tunnels.
+     *
+     * @throws GuacamoleException
+     *     If the session associated with the given auth token cannot be
+     *     retrieved.
+     */
+    @GET
+    public Set<String> getTunnelUUIDs(@QueryParam("token") String authToken)
+            throws GuacamoleException {
+        GuacamoleSession session = authenticationService.getGuacamoleSession(authToken);
+        return session.getTunnels().keySet();
+    }
+
+    /**
+     * Intercepts and returns the entire contents of a specific stream.
+     *
+     * @param authToken
+     *     The authentication token that is used to authenticate the user
+     *     performing the operation.
+     *
+     * @param tunnelUUID
+     *     The UUID of the tunnel containing the stream being intercepted.
+     *
+     * @param streamIndex
+     *     The index of the stream to intercept.
+     *
+     * @param mediaType
+     *     The media type (mimetype) of the data within the stream.
+     *
+     * @param filename
+     *     The filename to use for the sake of identifying the data returned.
+     *
+     * @return
+     *     A response through which the entire contents of the intercepted
+     *     stream will be sent.
+     *
+     * @throws GuacamoleException
+     *     If the session associated with the given auth token cannot be
+     *     retrieved, or if no such tunnel exists.
+     */
+    @GET
+    @Path("/{tunnel}/streams/{index}/{filename}")
+    public Response getStreamContents(@QueryParam("token") String authToken,
+            @PathParam("tunnel") String tunnelUUID,
+            @PathParam("index") final int streamIndex,
+            @QueryParam("type") @DefaultValue(DEFAULT_MEDIA_TYPE) String mediaType,
+            @PathParam("filename") String filename)
+            throws GuacamoleException {
+
+        GuacamoleSession session = authenticationService.getGuacamoleSession(authToken);
+        Map<String, StreamInterceptingTunnel> tunnels = session.getTunnels();
+
+        // STUB: For sake of testing, if only one tunnel exists, use that
+        if (tunnels.size() == 1)
+            tunnelUUID = tunnels.keySet().iterator().next();
+
+        // Pull tunnel with given UUID
+        final StreamInterceptingTunnel tunnel = tunnels.get(tunnelUUID);
+        if (tunnel == null)
+            throw new GuacamoleResourceNotFoundException("No such tunnel.");
+
+        // Intercept all output
+        StreamingOutput stream = new StreamingOutput() {
+
+            @Override
+            public void write(OutputStream output) throws IOException {
+                tunnel.interceptStream(streamIndex, output);
+            }
+
+        };
+
+        return Response.ok(stream, mediaType).build();
+
+    }
+
+}

guacamole/src/main/webapp/app/rest/services/tunnelService.js

@@ -0,0 +1,127 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Service for operating on the tunnels of in-progress connections (and their
+ * underlying objects) via the REST API.
+ */
+angular.module('rest').factory('tunnelService', ['$injector',
+        function tunnelService($injector) {
+
+    // Required services
+    var $http                 = $injector.get('$http');
+    var $window               = $injector.get('$window');
+    var authenticationService = $injector.get('authenticationService');
+
+    var service = {};
+
+    /**
+     * Reference to the window.document object.
+     *
+     * @private
+     * @type HTMLDocument
+     */
+    var document = $window.document;
+
+    /**
+     * Makes a request to the REST API to get the list of all tunnels
+     * associated with in-progress connections, returning a promise that
+     * provides an array of their UUIDs (strings) if successful.
+     *
+     * @returns {Promise.<String[]>>}
+     *     A promise which will resolve with an array of UUID strings, uniquely
+     *     identifying each active tunnel.
+     */
+    service.getTunnels = function getTunnels() {
+
+        // Build HTTP parameters set
+        var httpParameters = {
+            token : authenticationService.getCurrentToken()
+        };
+
+        // Retrieve tunnels
+        return $http({
+            method  : 'GET',
+            url     : 'api/tunnels',
+            params  : httpParameters
+        });
+
+    };
+
+    /**
+     * Makes a request to the REST API to retrieve the contents of a stream
+     * which has been created within the active Guacamole connection associated
+     * with the given tunnel. The contents of the stream will automatically be
+     * downloaded by the browser.
+     *
+     * WARNING: Like Guacamole's various reader implementations, this function
+     * relies on assigning an "onend" handler to the stream object for the sake
+     * of cleaning up resources after the stream closes. If the "onend" handler
+     * is overwritten after this function returns, resources may not be
+     * properly cleaned up.
+     *
+     * @param {String} tunnel
+     *     The UUID of the tunnel associated with the Guacamole connection
+     *     whose stream should be downloaded as a file.
+     *
+     * @param {Guacamole.InputStream} stream
+     *     The stream whose contents should be downloaded.
+     *
+     * @param {String} mimetype
+     *     The mimetype of the stream being downloaded. This is currently
+     *     ignored, with the download forced by using
+     *     "application/octet-stream".
+     *
+     * @param {String} filename
+     *     The filename that should be given to the downloaded file.
+     */
+    service.downloadStream = function downloadStream(tunnel, stream, mimetype, filename) {
+
+        // Build download URL
+        var url = $window.location.origin
+                + $window.location.pathname
+                + 'api/tunnels/' + encodeURIComponent(tunnel)
+                + '/streams/' + encodeURIComponent(stream.index)
+                + '/' + encodeURIComponent(filename)
+                + '?token=' + encodeURIComponent(authenticationService.getCurrentToken());
+
+        // Create temporary hidden iframe to facilitate download
+        var iframe = document.createElement('iframe');
+        iframe.style.position = 'fixed';
+        iframe.style.width = '1px';
+        iframe.style.height = '1px';
+        iframe.style.left = '-1px';
+        iframe.style.top = '-1px';
+
+        // The iframe MUST be part of the DOM for the download to occur
+        document.body.appendChild(iframe);
+
+        // Automatically remove iframe from DOM when download completes
+        stream.onend = function downloadComplete() {
+            document.body.removeChild(iframe);
+        };
+
+        // Begin download
+        iframe.src = url;
+
+    };
+
+    return service;
+
+}]);