Package com.subzero.spring

Class Subzero

java.lang.Object
com.subzero.spring.Subzero
public class Subzero extends Object
The main class for Subzero. It is used to handle HTTP requests in the context of a spring application.

  • Field Details

  • Constructor Details

    • Subzero

      public Subzero(DataSource dataSource, String dbType, String dbSchemaJson, String licenseKey) throws com.fasterxml.jackson.core.JsonProcessingException, SubzeroException
      Constructor for Subzero, used when the json schema is already known (for example when it's cached in a file)
      Parameters:
      dataSource - the data source to connect to the database
      dbType - the type of the database (postgresql, mysql, etc)
      dbSchemaJson - json representation of the database schema
      licenseKey - the license key for subzero (use null for demo mode)
      Throws:
      com.fasterxml.jackson.core.JsonProcessingException
      SubzeroException

    • Subzero

      public Subzero(DataSource dataSource, String dbType, String[] dbSchemas, String introspectionQueryDir, Boolean useInternalPermissions, String customRelations, String customPermissions, String licenseKey) throws SQLException, com.fasterxml.jackson.core.JsonProcessingException, SubzeroException
      Constructor for Subzero, used when the json schema is not known and needs to be introspected from the database
      Parameters:
      dataSource - the data source to connect to the database
      dbType - the type of the database (postgresql, mysql, etc)
      dbSchemas - the schemas to introspect and expose for the REST API
      introspectionQueryDir - the directory where the introspection queries are stored (optional, use null for default)
      useInternalPermissions - Set this to false if you want to rely on the database permissions only and bypass permission checks in Subzero.
      customRelations - custom relations to be added to the schema. This is useful when the introspection does not capture all the relations in the database (ex. with views) The parameters is a json string with the following format: 
      
        [
          {
            "constraint_name": "projects_client_id_fkey",
            "table_schema": "public",
            "table_name": "projects",
            "columns": ["client_id"],
            "foreign_table_schema": "public",
            "foreign_table_name": "clients",
            "foreign_columns": ["id"],
          },
          ...
        ]
      customPermissions - custom permissions to be added to the schema. This is used when you don't want to rely on the database permissions (database roles) to control access to the data. The permission system is still similar to the database RBAC+RLS, but it's managed by Subzero. The parameters is a json string. For the format, see this link: https://github.com/subzerocloud/showcase/blob/main/flyio-sqlite-litefs/permissions.js
      licenseKey - the license key for subzero (use null for demo mode)
      Throws:
      SQLException
      com.fasterxml.jackson.core.JsonProcessingException
      SubzeroException

  • Method Details

    • handleRequest

      public void handleRequest(String schema_name, String prefix, String role, jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res, String[] env, String max_rows) throws IOException, SubzeroException
      Handles an HTTP request. It will execute the SQL statement and return the result as a JSON object.
      Parameters:
      schema_name - the name of the database schema for the current request. This has to be one of the schemas that were introspected and exposed by Subzero. In the context of PostgreSQL, this is the schema name, in the context of MySQL, this is the database name.
      prefix - the prefix for the url. For example when the url is /api/v1/employees?select=id,name, the prefix is /api/v1/ (including the trailing slash)
      role - the role for the current request.
      req - the HTTP request object
      res - the HTTP response object
      env - the environment variables for the current request. This is an array of strings in the format ["name1", "value1", "name2", "value2", ...]. This is useful for passing to the SQL context aditional information that is not part of the request itself. Example: 
      
 [
   "request.method", "GET",
   "request.path", "/api/v1/employees",
   "request.jwt.claims", "{\"role\":\"admin\"}",
   "role", "admin"
 ]
      max_rows - the maximum number of rows that can be returned by a select statement. This should be an integer in string format. Use null for no limit.
      Throws:
      IOException
      SubzeroException

    • fmtContentRangeHeader

      public static String fmtContentRangeHeader(int lower, int upper, Integer total)

    • getSchema

      public Map<String,Object> getSchema(String currentRole, String schemaName)

    • getPermissions

      public Map<String,Object> getPermissions(String currentRole, String schemaName)

    • getEnv

      public Map<String,String> getEnv(String role, jakarta.servlet.http.HttpServletRequest request, Map<String,Object> jwtClaims)
      Returns the default environment variables for a request that can be passed to the handleRequest method and passed to the SQL context. The environment variables set are the following: - role: the role for the current request. In the context of PostgreSQL, this this env variable will change the current role for the session. - request.method: the HTTP method for the current request - request.path: the path for the current request - request.headers: the headers for the current request, single parameter as a json string - request.get: the query parameters for the current request, single parameter as a json string - request.jwt.claims: the JWT claims for the current request, single parameter as a json string
      Parameters:
      role - the user role for the current request
      request - the HTTP request object
      jwtClaims - the JWT claims for the current request
      Returns:
      a map with the environment variables. While handleRequest expects String[], this method returns a map for easier manipulation. The map can be converted to a String[] using the following code: 
      
 HashMap<String, String> env = subzero.getEnv("alice", req, Optional.of(jwtClaims));
 String[] envArray = new String[env.size() * 2];
 int i = 0;
 for (String key : env.keySet()) {
    envArray[i++] = key;
    envArray[i++] = env.get(key);
 }

    • loadNativeLibFromJar

      public static void loadNativeLibFromJar()
      Load the native library from the jar file This will try to load subzero and subzerojni native shared libraries from the jar file