You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@guacamole.apache.org by "mike-jumper (via GitHub)" <gi...@apache.org> on 2023/04/05 17:02:03 UTC
[GitHub] [guacamole-client] mike-jumper commented on a diff in pull request #809: GUACAMOLE-926: Batch Connection Import
mike-jumper commented on code in PR #809:
URL: https://github.com/apache/guacamole-client/pull/809#discussion_r1158728924
##########
extensions/guacamole-auth-jdbc/modules/guacamole-auth-jdbc-base/src/main/java/org/apache/guacamole/auth/jdbc/base/JDBCDirectory.java:
##########
@@ -0,0 +1,44 @@
+/*
+ * 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.auth.jdbc.base;
+
+import org.apache.guacamole.GuacamoleException;
+import org.apache.guacamole.net.auth.AtomicDirectoryOperation;
+import org.apache.guacamole.net.auth.Directory;
+import org.apache.guacamole.net.auth.Identifiable;
+import org.mybatis.guice.transactional.Transactional;
+
+/**
+ * An implementation of Directory that uses database transactions to guarantee
+ * atomicity for any operations supplied to tryAtomically().
+ */
+public abstract class JDBCDirectory<ObjectType extends Identifiable>
+ extends RestrictedObject implements Directory<ObjectType> {
+
+ @Transactional
+ public void tryAtomically(AtomicDirectoryOperation<ObjectType> operation)
Review Comment:
If this is inherited from `Directory` it should be annotated with `@Overrides`.
##########
guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AtomicDirectoryOperation.java:
##########
@@ -0,0 +1,57 @@
+/*
+ * 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.net.auth;
+
+import org.apache.guacamole.GuacamoleException;
+
+/**
+ * An operation that should be attempted atomically when passed to
+ * {@link Directory#tryAtomically}, if atomic operations are supported by
+ * the Directory.
+ */
+public interface AtomicDirectoryOperation<ObjectType extends Identifiable> {
+
+ /**
+ * Attempt the operation atomically. If the Directory does not support
+ * atomic operations, the atomic flag will be set to false. If the atomic
+ * flag is set to true, the provided directory is guaranteed to perform
+ * the operations within this function atomically. Atomicity of the
+ * provided directory outside this function, or of the directory invoking
+ * this function are not guaranteed.
+ *
+ * NOTE: If atomicity is required for this operation, a GuacamoleException
+ * may be thrown by this function before any changes are made, ensuring the
+ * operation will only ever be performed atomically.
Review Comment:
I think you may need an explicit `<p>` for JavaDoc to know that you intend a second paragraph.
##########
guacamole/src/main/java/org/apache/guacamole/rest/jsonpatch/APIPatchFailureException.java:
##########
@@ -0,0 +1,66 @@
+/*
+ * 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.jsonpatch;
+
+import java.util.List;
+
+import org.apache.guacamole.GuacamoleClientException;
+
+/**
+ * An exception describing a failure to apply the patches from a JSON Patch
+ * request. A list of outcomes is included, one for each patch in the request.
+ */
+public class APIPatchFailureException extends GuacamoleClientException {
Review Comment:
Recommend instead extending `TranslatableGuacamoleClientException` so that failures may be translated.
##########
guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AtomicDirectoryOperation.java:
##########
@@ -0,0 +1,57 @@
+/*
+ * 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.net.auth;
+
+import org.apache.guacamole.GuacamoleException;
+
+/**
+ * An operation that should be attempted atomically when passed to
+ * {@link Directory#tryAtomically}, if atomic operations are supported by
+ * the Directory.
+ */
+public interface AtomicDirectoryOperation<ObjectType extends Identifiable> {
+
+ /**
+ * Attempt the operation atomically. If the Directory does not support
+ * atomic operations, the atomic flag will be set to false. If the atomic
+ * flag is set to true, the provided directory is guaranteed to perform
+ * the operations within this function atomically. Atomicity of the
+ * provided directory outside this function, or of the directory invoking
Review Comment:
if*
##########
guacamole/src/main/frontend/src/app/rest/services/userService.js:
##########
@@ -235,6 +235,39 @@ angular.module('rest').factory('userService', ['$injector',
});
};
+
+ /**
+ * Makes a request to the REST API to apply a supplied list of user patches,
+ * returning a promise that can be used for processing the results of the
+ * call.
+ *
+ * This operation is atomic - if any errors are encountered during the
+ * connection patching process, the entire request will fail, and no
+ * changes will be persisted.
+ *
+ * @param {DirectoryPatch.<User>[]} patches
+ * An array of patches to apply.
+ *
+ * @returns {Promise}
+ * A promise for the HTTP call which will succeed if and only if the
+ * patch operation is successful.
+ */
+ service.patchUsers = function patchUsers(dataSource, patches) {
+
+ // Make the PATCH request
+ return authenticationService.request({
+ method : 'PATCH',
+ url : 'api/session/data/' + encodeURIComponent(dataSource) + '/users',
+ data : patches
+ })
+
+ // Clear the cache
+ .then(function usersPatched(patchResponse){
+ cacheService.users.removeAll();
+ return patchResponse;
+ });
+
+ }
Review Comment:
Missing semicolon here.
##########
guacamole/src/main/frontend/src/app/rest/types/DirectoryPatchOutcome.js:
##########
@@ -0,0 +1,79 @@
+/*
+ * 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 which defines the DirectoryPatchOutcome class.
+ */
+angular.module('rest').factory('DirectoryPatchOutcome', [
+ function defineDirectoryPatchOutcome() {
+
+ /**
+ * An object returned by a PATCH request to a directory REST API,
+ * representing the outcome associated with a particular patch in the
+ * request. This object can indicate either a successful or unsuccessful
+ * response. The error field is only meaningful for unsuccessful patches.
+ * @constructor
+ *
+ * @param {DirectoryPatchOutcome|Object} [template={}]
+ * The object whose properties should be copied within the new
+ * DirectoryPatchOutcome.
+ */
+ const DirectoryPatchOutcome = function DirectoryPatchOutcome(template) {
+
+ // Use empty object by default
+ template = template || {};
+
+ /**
+ * The operation to apply to the objects indicated by the path. Valid
+ * operation values are defined within DirectoryPatch.Operation.
+ *
+ * @type {String}
+ */
+ this.op = template.op;
+
+ /**
+ * The path of the object operated on by the corresponding patch in the
+ * request.
+ *
+ * @type {String}
+ */
+ this.path = template.path;
+
+ /**
+ * The identifier of the object operated on by the corresponding patch
+ * in the request. If the object was newly created and the PATCH request
+ * did not fail, this will be the identifier of the newly created object.
+ *
+ * @type {String}
+ */
+ this.identifier = template.identifier;
+
+ /**
+ * The error message associated with the failure, if the patch failed to
+ * apply.
+ *
+ * @type {String}
+ */
+ this.error = template.error;
Review Comment:
I suspect this should be a `TranslatableMessage`.
##########
guacamole/src/main/frontend/src/app/rest/services/connectionService.js:
##########
@@ -154,6 +156,45 @@ angular.module('rest').factory('connectionService', ['$injector',
}
};
+
+ /**
+ * Makes a request to the REST API to apply a supplied list of connection
+ * patches, returning a promise that can be used for processing the results
+ * of the call.
+ *
+ * This operation is atomic - if any errors are encountered during the
+ * connection patching process, the entire request will fail, and no
+ * changes will be persisted.
+ *
+ * @param {DirectoryPatch.<Connection>[]} patches
+ * An array of patches to apply.
+ *
+ * @returns {Promise}
+ * A promise for the HTTP call which will succeed if and only if the
+ * patch operation is successful.
+ */
+ service.patchConnections = function patchConnections(dataSource, patches) {
Review Comment:
Please document the `dataSource` parameter.
##########
guacamole/src/main/frontend/src/app/rest/services/connectionService.js:
##########
@@ -154,6 +156,45 @@ angular.module('rest').factory('connectionService', ['$injector',
}
};
+
+ /**
+ * Makes a request to the REST API to apply a supplied list of connection
+ * patches, returning a promise that can be used for processing the results
+ * of the call.
+ *
+ * This operation is atomic - if any errors are encountered during the
+ * connection patching process, the entire request will fail, and no
+ * changes will be persisted.
+ *
+ * @param {DirectoryPatch.<Connection>[]} patches
+ * An array of patches to apply.
+ *
+ * @returns {Promise}
+ * A promise for the HTTP call which will succeed if and only if the
+ * patch operation is successful.
+ */
+ service.patchConnections = function patchConnections(dataSource, patches) {
Review Comment:
Please document the `dataSource` parameter.
##########
guacamole/src/main/frontend/src/app/rest/types/DirectoryPatch.js:
##########
@@ -0,0 +1,89 @@
+/*
+ * 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 which defines the DirectoryPatch class.
+ */
+angular.module('rest').factory('DirectoryPatch', [function defineDirectoryPatch() {
+
+ /**
+ * The object consumed by REST API calls when representing changes to an
+ * arbitrary set of directory-based objects.
+ * @constructor
+ *
+ * @template DirectoryObject
+ * The directory-based object type that this DirectoryPatch will
+ * operate on.
+ *
+ * @param {DirectoryObject|Object} [template={}]
+ * The object whose properties should be copied within the new
+ * DirectoryPatch.
+ */
+ var DirectoryPatch = function DirectoryPatch(template) {
+
+ // Use empty object by default
+ template = template || {};
+
+ /**
+ * The operation to apply to the objects indicated by the path. Valid
+ * operation values are defined within DirectoryPatch.Operation.
+ *
+ * @type {String}
+ */
+ this.op = template.op;
+
+ /**
+ * The path of the objects to modify. For creation of new objects, this
+ * should be "/". Otherwise, it should be "/{identifier}", specifying
+ * the identifier of the existing object being modified.
+ *
+ * @type {String}
+ * @default '/'
+ */
+ this.path = template.path || '/';
+
+ /**
+ * The object being added, or undefined if deleting.
+ *
+ * @type {DirectoryObject}
+ */
+ this.value = template.value;
+
+ };
+
+ /**
+ * All valid patch operations for directory-based objects.
+ */
+ DirectoryPatch.Operation = {
+
+ /**
+ * Adds the specified object to the relation.
+ */
+ ADD : "add",
+
+ /**
+ * Removes the specified object from the relation.
+ */
+ REMOVE : "remove"
Review Comment:
Please use `'` for JS strings: https://guacamole.apache.org/guac-style/#naming
##########
guacamole/src/main/java/org/apache/guacamole/rest/jsonpatch/APIPatchError.java:
##########
@@ -0,0 +1,71 @@
+/*
+ * 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.jsonpatch;
+
+import org.apache.guacamole.rest.jsonpatch.APIPatch.Operation;
+
+/**
+ * A failure outcome associated with a particular patch within a JSON Patch
+ * request. This status indicates that a particular patch failed to apply,
+ * and includes the error describing the failure, along with the operation and
+ * path from the original patch, and the identifier of the object
+ * referenced by the original patch.
+ */
+public class APIPatchError extends APIPatchOutcome {
+
+ /**
+ * The error associated with the submitted patch.
+ */
+ private final String error;
+
+ /**
+ * Create a failure status associated with a submitted patch from a JSON
+ * patch API request.
+ *
+ * @param op
+ * The operation requested by the failed patch.
+ *
+ * @param identifier
+ * The identifier of the object associated with the failed patch. If
+ * the patch failed to create a new object, this will be null.
+ *
+ * @param path
+ * The patch from the failed patch.
+ *
+ * @param error
+ * The error message associated with the failure that prevented the
+ * patch from applying.
+ */
+ public APIPatchError(
+ Operation op, String identifier, String path, String error) {
+ super(op, identifier, path);
+ this.error = error;
+ }
+
+ /**
+ * Return the error associated with the patch failure.
+ *
+ * @return
+ * The error associated with the patch failure.
+ */
+ public String getError() {
+ return error;
+ }
Review Comment:
Should this instead be a `TranslatableMessage`?
##########
guacamole/src/main/frontend/src/app/rest/services/userGroupService.js:
##########
@@ -190,6 +190,39 @@ angular.module('rest').factory('userGroupService', ['$injector',
};
+ /**
+ * Makes a request to the REST API to apply a supplied list of user group
+ * patches, returning a promise that can be used for processing the results
+ * of the call.
+ *
+ * This operation is atomic - if any errors are encountered during the
+ * connection patching process, the entire request will fail, and no
+ * changes will be persisted.
+ *
+ * @param {DirectoryPatch.<UserGroup>[]} patches
+ * An array of patches to apply.
+ *
+ * @returns {Promise}
+ * A promise for the HTTP call which will succeed if and only if the
+ * patch operation is successful.
+ */
+ service.patchUserGroups = function patchUserGroups(dataSource, patches) {
+
+ // Make the PATCH request
+ return authenticationService.request({
+ method : 'PATCH',
+ url : 'api/session/data/' + encodeURIComponent(dataSource) + '/userGroups',
+ data : patches
+ })
+
+ // Clear the cache
+ .then(function userGroupsPatched(patchResponse){
+ cacheService.users.removeAll();
+ return patchResponse;
+ });
+
+ }
Review Comment:
Missing semicolon here.
##########
guacamole/src/main/frontend/src/app/rest/services/userGroupService.js:
##########
@@ -190,6 +190,39 @@ angular.module('rest').factory('userGroupService', ['$injector',
};
+ /**
+ * Makes a request to the REST API to apply a supplied list of user group
+ * patches, returning a promise that can be used for processing the results
+ * of the call.
+ *
+ * This operation is atomic - if any errors are encountered during the
+ * connection patching process, the entire request will fail, and no
+ * changes will be persisted.
+ *
+ * @param {DirectoryPatch.<UserGroup>[]} patches
+ * An array of patches to apply.
+ *
+ * @returns {Promise}
+ * A promise for the HTTP call which will succeed if and only if the
+ * patch operation is successful.
+ */
+ service.patchUserGroups = function patchUserGroups(dataSource, patches) {
Review Comment:
Please document the `dataSource` parameter.
##########
guacamole/src/main/frontend/src/app/rest/services/userService.js:
##########
@@ -235,6 +235,39 @@ angular.module('rest').factory('userService', ['$injector',
});
};
+
+ /**
+ * Makes a request to the REST API to apply a supplied list of user patches,
+ * returning a promise that can be used for processing the results of the
+ * call.
+ *
+ * This operation is atomic - if any errors are encountered during the
+ * connection patching process, the entire request will fail, and no
+ * changes will be persisted.
+ *
+ * @param {DirectoryPatch.<User>[]} patches
+ * An array of patches to apply.
+ *
+ * @returns {Promise}
+ * A promise for the HTTP call which will succeed if and only if the
+ * patch operation is successful.
+ */
+ service.patchUsers = function patchUsers(dataSource, patches) {
Review Comment:
Please document the `dataSource` parameter.
##########
guacamole/src/main/frontend/src/app/rest/services/connectionService.js:
##########
@@ -154,6 +156,45 @@ angular.module('rest').factory('connectionService', ['$injector',
}
};
+
+ /**
+ * Makes a request to the REST API to apply a supplied list of connection
+ * patches, returning a promise that can be used for processing the results
+ * of the call.
+ *
+ * This operation is atomic - if any errors are encountered during the
+ * connection patching process, the entire request will fail, and no
+ * changes will be persisted.
+ *
+ * @param {DirectoryPatch.<Connection>[]} patches
+ * An array of patches to apply.
+ *
+ * @returns {Promise}
+ * A promise for the HTTP call which will succeed if and only if the
+ * patch operation is successful.
+ */
+ service.patchConnections = function patchConnections(dataSource, patches) {
+
+ // Make the PATCH request
+ return authenticationService.request({
+ method : 'PATCH',
+ url : 'api/session/data/' + encodeURIComponent(dataSource) + '/connections',
+ data : patches
+ })
+
+ // Clear the cache
+ .then(function connectionsPatched(patchResponse){
+ cacheService.connections.removeAll();
+
+ // Clear users cache to force reload of permissions for any
+ // newly created or replaced connections
+ cacheService.users.removeAll();
+
+ return patchResponse;
+
+ });
+
+ }
Review Comment:
Same here - missing semicolon.
##########
guacamole/src/main/frontend/src/app/import/templates/connectionImportFileHelp.html:
##########
@@ -0,0 +1,93 @@
+<div class="import help">
+
+ <div class="header">
+ <h2>{{'IMPORT.SECTION_HEADER_HELP_CONNECTION_IMPORT_FILE' | translate}}</h2>
+ <guac-user-menu></guac-user-menu>
+ </div>
+
+ <h2>{{'IMPORT.HELP_FILE_TYPE_HEADER' | translate}}</h2>
+ <p>{{'IMPORT.HELP_FILE_TYPE_DESCRIPTION' | translate}}</p>
+
+ <h2>{{'IMPORT.HELP_CSV_HEADER' | translate}}</h2>
+ <p>{{'IMPORT.HELP_CSV_DESCRIPTION' | translate}}</p>
+ <p>{{'IMPORT.HELP_CSV_MORE_DETAILS' | translate}}</p>
+ <pre>name,protocol,hostname,group,users,groups,guacd-encryption (attribute)
+conn1,vnc,conn1.web.com,ROOT,guac user 1;guac user 2,Connection 1 Users,none
+conn2,rdp,conn2.web.com,ROOT/Parent Group,guac user 1,,ssl
+conn3,ssh,conn3.web.com,ROOT/Parent Group/Child Group,guac user 2;guac user 3,,
+conn4,kubernetes,,,,,</pre>
Review Comment:
Since the example CSV itself contains English that's meant to be human-readable, I think it should be (if possible). Does angular-translate strip newlines from the translated text? If not, I'd think we could have something like:
"IMPORT" : {
"INFO_EXAMPLE_CSV" : "a,b,c\n1,2,3\n4,5,6"
},
and:
<pre>{{ 'IMPORT.INFO_EXAMPLE_CSV' | translate }}</pre>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@guacamole.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org