Merge pull request #621 from kbase/develop

Release 0.13.2 (develop -> master)

.classpath

@@ -103,5 +103,6 @@
 	<classpathentry kind="lib" path="/jars/lib/jars/picocli/picocli-4.6.1.jar"/>
 	<classpathentry kind="lib" path="/jars/lib/jars/kbase/sample/SampleServiceClient-0.1.1.jar"/>
 	<classpathentry kind="lib" path="/jars/lib/jars/mongo/mongo-java-driver-3.12.10.jar"/>
+	<classpathentry kind="lib" path="/jars/lib/jars/caffeinecache/caffeine-2.9.3.jar"/>
 	<classpathentry kind="output" path="bin"/>
 </classpath>

build.xml

@@ -67,6 +67,7 @@
     <include name="logback/logback-core-1.1.2.jar"/>
     <include name="logback/logback-classic-1.1.2.jar"/>
     <include name="google/guava-14.0.1.jar"/>
+    <include name="caffeinecache/caffeine-2.9.3.jar"/>
     <include name="kafka/kafka-clients-2.1.0.jar"/>
     <include name="kbase/handle/AbstractHandleClient-1.0.0.jar"/>
     <include name="kbase/sample/SampleServiceClient-0.1.1.jar"/>

deploy.cfg.example

@@ -26,6 +26,12 @@ mongodb-database = workspace
 # result in unspecified behavior, including data corruption.
 mongodb-type-database = types
 
+# URL for a workspace to which type operations will be delegated. If provided, the
+# mongodb-type-database setting is ignored.
+# WARNING: See the workspace documentation for detailed instructions on correctly setting up
+# type delegation.
+# type-delegation-target = 
+
 # The legacy KBase authorization server url.
 auth-service-url = https://kbase.us/services/auth/api/legacy/KBase/Sessions/Login
 

deployment/conf/.templates/deployment.cfg.templ

@@ -1,6 +1,7 @@
 [Workspace]
 mongodb-database={{ default .Env.mongodb_database "workspace" }}
 mongodb-type-database={{ default .Env.mongodb_type_database "workspace_type_db" }}
+type-delegation-target={{ default .Env.type_delegation_target "" }}
 mongodb-retrywrites={{ default .Env.mongodb_retrywrites "false" }}
 mongodb-pwd={{ default .Env.mongodb_pwd "" }}
 ws-admin={{ default .Env.ws_admin "scanonadmin" }}

docsource/administrationinterface.rst

@@ -16,6 +16,17 @@ First initialize a workspace client with administrator credentials::
    These examples use the Python client, but translating the commands to
    other languages is trivial.
 
+Getting type delegation information
+-----------------------------------
+
+Getting the url of the workspace service to which the current workspace service is delegating
+type operations::
+
+    wsadmin.administer({'command': 'getTypeDelegationTarget'})
+    {'delegateTarget', 'https://kbase.us/services/ws_for_types'}
+
+See :ref:`workspacescaling` for more information.
+
 Managing administrators
 -----------------------
 

docsource/admins.rst

@@ -7,6 +7,7 @@ Server Administrator Documentation
    buildandconfigure
    test
    events
+   workspacescaling
    resourcereqs
    administrationinterface
    upgrades

docsource/buildandconfigure.rst

@@ -157,11 +157,23 @@ mongodb-database
 
 mongodb-type-database
 """""""""""""""""""""
-**Required**: Yes
+**Required**: If not delegating type operations
 
 **Description**: Name of the workspace MongoDB types database. This database name must not be
 the same as ``mongodb-database``.
 
+.. warning:: Once any data has been saved by the workspace, changing the type database will
+   result in unspecified behavior, including data corruption.
+
+type-delegation-target
+""""""""""""""""""""""
+**Required**: If delegating type operations
+
+**Description**: URL of the workspace service to which type operations should be delegated. If
+this parameter is set ``mongodb-type-database`` is ignored.
+
+.. warning:: Read :ref:`workspacescaling` carefully before delegating types.
+
 .. warning:: Once any data has been saved by the workspace, changing the type database will
    result in unspecified behavior, including data corruption.
 

docsource/conf.py

@@ -52,7 +52,7 @@
 # The short X.Y version.
 version = '0.13'
 # The full version, including alpha/beta/rc tags.
-release = '0.13.1'
+release = '0.13.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docsource/knownadminbugs.rst

@@ -1,12 +1,9 @@
 Known administration bugs
 =========================
 
-* The WSS occasionally fails to start after a redeploy without restarting
-  Glassfish, usually after 25-30 redeploys. Workaround by killing and
-  restarting Glassfish.
-
 * Due to application level locks in the type database portion of the server,
-  only one instance of the server can be run at once. 
+  only one instance of the server can be run at once. However, see
+  :ref:`workspacescaling` for a workaround. 
 
 .. note::
    In the future the type service may be separated from the workspace service,

docsource/releasenotes.rst

@@ -3,6 +3,14 @@
 Workspace service release notes
 ===============================
 
+VERSION: 0.13.2 (Released 6/1/2022)
+-----------------------------------
+
+UPDATES:
+
+* Type delegation has been added. See :ref:`workspacescaling` for more information.
+* The ``get_func_info`` and ``get_all_func_info`` methods are deprecated.
+
 VERSION: 0.13.1 (Released 4/27/2022)
 ------------------------------------
 

docsource/workspacescaling.rst

@@ -0,0 +1,62 @@
+.. _workspacescaling:
+
+Workspace scaling
+=================
+
+When written, and to this day, the type database portion of the workspace incorporated
+application level read and write locks. This means that only one instance of the workspace
+can safely read and write from the type database at once, or data corruption may result. In
+turn, this means that the workspace is a single point of failure and cannot be horizontally scaled.
+
+Workspace version 0.13.2 introduced type delegation as a first step towards resolving this issue.
+With type delegation, one workspace can be set as the central type handler while all other
+workspaces delegate type operations to that workspace. The single workspace handles all writes
+and reads to the type database; since the load on the type database is extremely low compared
+to the workspace proper, this allows scaling the high load portion of the work the Workspace
+handles. It also means that only the type handling Workspace becomes a single point of
+failure - many Workspace instances can be deployed behind a load balancer to provide redundancy
+in case one fails.
+
+In the future we plan to split the type database from the workspace entirely to simplify setup
+and reduce the possibility of incorrect configuration of the workspaces in the set.
+
+Acronyms
+--------
+
+* TWS - the type Workspace service. The single workspace that handles reading and writing
+  type information from the type database.
+* DWS - delegating Workspace services. All other workspace services in the set. They must all
+  delegate type operations to the TWS.
+
+Set up
+------
+
+.. warning:: It is extremely important to be careful when setting up a workspace delegation set as
+   incorrect setup can result in corrupt type information or infinite delegation loops.
+
+Set up instructions:
+
+* All workspaces in the delegation set should have the same parameter settings in the deployment
+  configuration except for ``temp-dir`` and as discussed below. Differing configurations can lead
+  to many problems including data corruption, failing admin methods, etc.
+* For the TWS, the ``mongodb-type-database`` parameter should be set in the deploy configuration
+  file. See :ref:`configurationparameters` for details. **No other** workspace in the set may
+  have this parameter populated - if that happens, type data corruption may result. Similarly,
+  workspaces not in the set should not use the same type database.
+* All DWS in the set must have the ``type-delegation-target`` parameter set in the configuration
+  file, and the url must point to the TWS. Incorrectly setting the url will cause the DWS not
+  to start, or worse, create an infinite delegation loop.
+
+Deployment tips and notes
+-------------------------
+
+* Although all the workspaces in the delegation set can be exposed to users, it may be wise
+  to prevent contact to the TWS by any systems other than the DWS. This keeps the overall load
+  on the TWS low and reduces risk of a single point failure.
+* The DWS do not cache results from any type related service methods (such as ``get_module_info``)
+  or admin methods (such as ``approveModRequest``).
+* The DWS cache type JSONSchemas used for type checking objects in the ``save_objects`` method.
+  Up to 1MB of JSONSchemas are cached indefinitely with less frequently used schemas
+  expiring from the cache when it is full. Mappings from non-absolute types (e.g. ``Module.Type``
+  or ``Module.Type-2``) to absolute types (e.g. ``Module.Type-2.1``) are cached for 5 minutes
+  and infrequently used mappings are expired when the cache reaches its 100MB limit.

lib/Bio/KBase/workspace/Client.pm

@@ -7546,7 +7546,7 @@ type_string is a string
 
 =item Description
 
-
+@deprecated
 
 =back
 
@@ -7656,7 +7656,7 @@ type_string is a string
 
 =item Description
 
-
+@deprecated
 
 =back
 
@@ -12168,23 +12168,8 @@ used_type_defs has a value which is a reference to a list where each element is
 
 =item Description
 
-Information about a function
-
-        func_string func_def - resolved func definition id.
-        string description - the description of the function from spec file.
-        string spec_def - reconstruction of function definition from spec file.
-        string parsing_structure - json document describing parsing structure of function 
-                in spec file including types of arguments.
-        list<spec_version> module_vers - versions of spec files containing
-                given func version.
-        list<spec_version> released_module_vers - released versions of spec files 
-                containing given func version.
-        list<func_string> func_vers - all versions of function with given type
-                name.
-        list<func_string> released_func_vers - all released versions of function 
-                with given type name.
-        list<type_string> used_type_defs - list of types (with versions) 
-                referred to from this function version.
+DEPRECATED
+@deprecated
 
 
 =item Definition

lib/biokbase/workspace/client.py

@@ -5035,6 +5035,7 @@ def get_all_type_info(self, mod, context=None):
 
     def get_func_info(self, func, context=None):
         """
+        @deprecated
         :param func: instance of type "func_string" (A function string for
            referencing a funcdef. Specifies the function and its version in a
            single string in the format
@@ -5049,25 +5050,13 @@ def get_func_info(self, func, context=None):
            compatible with previous function definitions. In many cases, the
            major and minor versions are optional, and if not provided the
            most recent version will be used. Example: MyModule.MyFunc-3.1)
-        :returns: instance of type "FuncInfo" (Information about a function
-           func_string func_def - resolved func definition id. string
-           description - the description of the function from spec file.
-           string spec_def - reconstruction of function definition from spec
-           file. string parsing_structure - json document describing parsing
-           structure of function in spec file including types of arguments.
-           list<spec_version> module_vers - versions of spec files containing
-           given func version. list<spec_version> released_module_vers -
-           released versions of spec files containing given func version.
-           list<func_string> func_vers - all versions of function with given
-           type name. list<func_string> released_func_vers - all released
-           versions of function with given type name. list<type_string>
-           used_type_defs - list of types (with versions) referred to from
-           this function version.) -> structure: parameter "func_def" of type
-           "func_string" (A function string for referencing a funcdef.
-           Specifies the function and its version in a single string in the
-           format [modulename].[funcname]-[major].[minor]: modulename - a
-           string. The name of the module containing the function. funcname -
-           a string. The name of the function as assigned by the funcdef
+        :returns: instance of type "FuncInfo" (DEPRECATED @deprecated) ->
+           structure: parameter "func_def" of type "func_string" (A function
+           string for referencing a funcdef. Specifies the function and its
+           version in a single string in the format
+           [modulename].[funcname]-[major].[minor]: modulename - a string.
+           The name of the module containing the function. funcname - a
+           string. The name of the function as assigned by the funcdef
            statement. major - an integer. The major version of the function.
            A change in the major version implies the function has changed in
            a non-backwards compatible way. minor - an integer. The minor
@@ -5127,28 +5116,16 @@ def get_func_info(self, func, context=None):
 
     def get_all_func_info(self, mod, context=None):
         """
+        @deprecated
         :param mod: instance of type "modulename" (A module name defined in a
            KIDL typespec.)
-        :returns: instance of list of type "FuncInfo" (Information about a
-           function func_string func_def - resolved func definition id.
-           string description - the description of the function from spec
-           file. string spec_def - reconstruction of function definition from
-           spec file. string parsing_structure - json document describing
-           parsing structure of function in spec file including types of
-           arguments. list<spec_version> module_vers - versions of spec files
-           containing given func version. list<spec_version>
-           released_module_vers - released versions of spec files containing
-           given func version. list<func_string> func_vers - all versions of
-           function with given type name. list<func_string>
-           released_func_vers - all released versions of function with given
-           type name. list<type_string> used_type_defs - list of types (with
-           versions) referred to from this function version.) -> structure:
-           parameter "func_def" of type "func_string" (A function string for
-           referencing a funcdef. Specifies the function and its version in a
-           single string in the format
-           [modulename].[funcname]-[major].[minor]: modulename - a string.
-           The name of the module containing the function. funcname - a
-           string. The name of the function as assigned by the funcdef
+        :returns: instance of list of type "FuncInfo" (DEPRECATED
+           @deprecated) -> structure: parameter "func_def" of type
+           "func_string" (A function string for referencing a funcdef.
+           Specifies the function and its version in a single string in the
+           format [modulename].[funcname]-[major].[minor]: modulename - a
+           string. The name of the module containing the function. funcname -
+           a string. The name of the function as assigned by the funcdef
            statement. major - an integer. The major version of the function.
            A change in the major version implies the function has changed in
            a non-backwards compatible way. minor - an integer. The minor

src/us/kbase/typedobj/core/LocalTypeProvider.java

@@ -1,42 +1,32 @@
 package us.kbase.typedobj.core;
 
+import static java.util.Objects.requireNonNull;
+
 import us.kbase.typedobj.db.TypeDefinitionDB;
 import us.kbase.typedobj.exceptions.NoSuchModuleException;
 import us.kbase.typedobj.exceptions.NoSuchTypeException;
 import us.kbase.typedobj.exceptions.TypeStorageException;
 
 /** A type provider for the typed object validator that takes a direct instance
  * of a type database.
- * @author [email protected]
  *
  */
 public class LocalTypeProvider implements TypeProvider {
 
-	//TODO TEST unit tests
-
 	private final TypeDefinitionDB typeDB;
 
 	/** Create a type provider that connects directly to a type database.
 	 * @param typeDB a type database.
 	 */
 	public LocalTypeProvider(final TypeDefinitionDB typeDB) {
-		if (typeDB == null) {
-			throw new NullPointerException("typeDB cannot be null");
-		}
-		this.typeDB = typeDB;
-	}
-	@Override
-	public AbsoluteTypeDefId resolveTypeDef(TypeDefId typeDefId)
-			throws NoSuchTypeException, NoSuchModuleException,
-			TypeStorageException {
-		return typeDB.resolveTypeDefId(typeDefId);
+		this.typeDB = requireNonNull(typeDB, "typeDB");
 	}
 
 	@Override
-	public String getTypeJsonSchema(AbsoluteTypeDefId typeDefId)
-			throws NoSuchTypeException, NoSuchModuleException,
-			TypeStorageException {
-		return typeDB.getJsonSchemaDocument(typeDefId);
+	public ResolvedType getTypeJsonSchema(final TypeDefId type)
+			throws NoSuchTypeException, NoSuchModuleException, TypeStorageException {
+		final AbsoluteTypeDefId rtype = typeDB.resolveTypeDefId(requireNonNull(type, "type"));
+		return new ResolvedType(rtype, typeDB.getJsonSchemaDocument(rtype));
 	}
 
 }

src/us/kbase/typedobj/core/TypeDefName.java

@@ -8,8 +8,8 @@
 
 public class TypeDefName {
 
-	private final static Pattern INVALID_TYPE_NAMES = 
-			Pattern.compile("[^\\w]");
+	// In java, unlike, say, python 3, this is a-zA-Z0-9_ only, no unicode chars
+	private final static Pattern INVALID_TYPE_NAMES = Pattern.compile("[^\\w]");
 	private final static int MAX_NAME_SIZE_BYTES = 255;
 
 	private final String module;
@@ -27,7 +27,7 @@ public TypeDefName(String module, String name) {
 	 */
 	public TypeDefName(String fullname) {
 		String [] tokens = fullname.split("\\.");
-		if(tokens.length != 2) {
+		if (tokens.length != 2) {
 			throw new IllegalArgumentException(String.format(
 					"Illegal fullname of a typed object: %s", fullname));
 		}