Autogenerate Permissions API (#118)

Author: kartikgupta-db

packages/databricks-sdk-js/src/api-client.ts

@@ -7,7 +7,7 @@ import {CancellationToken} from "./types";
 
 const sdkVersion = require("../package.json").version;
 
-type HttpMethod = "POST" | "GET" | "DELETE" | "PATCH";
+type HttpMethod = "POST" | "GET" | "DELETE" | "PATCH" | "PUT";
 
 export class HttpError extends Error {
     constructor(

packages/databricks-sdk-js/src/apis/.codegen.json

@@ -1,7 +1,14 @@
 {
-    "includeTags": ["Clusters", "Jobs", "Repos", "Workspace", "Dbfs"],
+    "includeTags": [
+        "Clusters",
+        "Jobs",
+        "Repos",
+        "Workspace",
+        "Dbfs",
+        "Permissions"
+    ],
     "formatter": "yarn fix",
-    "fileset": {
+    "packages": {
         ".codegen/api.ts.tmpl": "{{.Name}}/api.ts",
         ".codegen/index.ts.tmpl": "{{.Name}}/index.ts",
         ".codegen/model.ts.tmpl": "{{.Name}}/model.ts"

packages/databricks-sdk-js/src/apis/.codegen/api.ts.tmpl

@@ -9,15 +9,15 @@ import retry from "../../retries/retries";
 import {CancellationToken} from "../../types"
 import {ApiError, ApiRetriableError} from "../apiError";
 
-{{- range $i, $s := .Services }}
+{{range $i, $s := .Services }}
 export class {{$s.PascalName}}RetriableError extends ApiRetriableError {
 	constructor(method: string, message?: string){
-		super("$s.PascalName", method, message)
+		super("{{$s.PascalName}}", method, message)
 	}
 }
 export class {{$s.PascalName}}Error extends ApiError {
 	constructor(method: string, message?: string){
-		super("$s.PascalName", method, message)
+		super("{{$s.PascalName}}", method, message)
 	}
 }
 
@@ -59,8 +59,8 @@ export class {{$s.PascalName}}Service {
 		return await retry<model.{{if .Wait.Poll.Response}}{{.Wait.Poll.Response.PascalName}}{{else}}{{.Wait.Poll.EmptyResponseName.PascalName}}{{end}}>({
 			timeout: timeout,
 			fn: async () => {
-				const pollResponse = await this.{{.Wait.Poll.CamelName}}({
-					{{.Wait.Bind.SnakeName}}: {{if .Wait.ForceBindRequest}}request{{else if .Response}}response{{else}}request{{end}}.{{.Wait.Bind.SnakeName}}!
+				const pollResponse = await this.{{.Wait.Poll.CamelName}}({ {{$e := .}}{{range .Wait.Binding}}
+					{{.Bind.SnakeName}}: {{if $e.Wait.ForceBindRequest}}request{{else if $e.Response}}response{{else}}request{{end}}.{{.Bind.SnakeName}}{{end}}!
 				}, cancellationToken)
 				if(cancellationToken?.isCancellationRequested) {
 					throw new {{$s.PascalName}}Error("{{.CamelName}}AndWait", "cancelled");

packages/databricks-sdk-js/src/apis/clusters/api.ts

@@ -8,14 +8,15 @@ import Time from "../../retries/Time";
 import retry from "../../retries/retries";
 import {CancellationToken} from "../../types";
 import {ApiError, ApiRetriableError} from "../apiError";
+
 export class ClustersRetriableError extends ApiRetriableError {
     constructor(method: string, message?: string) {
-        super("$s.PascalName", method, message);
+        super("Clusters", method, message);
     }
 }
 export class ClustersError extends ApiError {
     constructor(method: string, message?: string) {
-        super("$s.PascalName", method, message);
+        super("Clusters", method, message);
     }
 }
 
@@ -25,8 +26,10 @@ export class ClustersError extends ApiError {
 export class ClustersService {
     constructor(readonly client: ApiClient) {}
     /**
-     * Public version of editClusterOwner, allowing admins to change cluster
-     * owner
+     * Change cluster owner
+     *
+     * Change the owner of the cluster. You must be an admin to perform this
+     * operation.
      */
     async changeOwner(
         request: model.ChangeClusterOwner,
@@ -42,24 +45,21 @@ export class ClustersService {
     }
 
     /**
+     * Create new cluster
+     *
      * Creates a new Spark cluster. This method will acquire new instances from
      * the cloud provider if necessary. This method is asynchronous; the returned
      * ``cluster_id`` can be used to poll the cluster status. When this method
-     * returns, the cluster will be in a ``PENDING`` state. The cluster will be
-     * usable once it enters a ``RUNNING`` state. Note: Databricks may not be
-     * able to acquire some of the requested nodes, due to cloud provider
-     * limitations (account limits, spot price, ...) or transient network issues.
+     * returns, the cluster will be in\na ``PENDING`` state. The cluster will be
+     * usable once it enters a ``RUNNING`` state.
+     *
+     * Note: Databricks may not be able to acquire some of the requested nodes,
+     * due to cloud provider limitations (account limits, spot price, etc.) or
+     * transient network issues.
+     *
      * If Databricks acquires at least 85% of the requested on-demand nodes,
      * cluster creation will succeed. Otherwise the cluster will terminate with
-     * an informative error message. An example request: .. code:: {
-     * "cluster_name": "my-cluster", "spark_version": "2.0.x-scala2.10",
-     * "node_type_id": "r3.xlarge", "spark_conf": { "spark.speculation": true },
-     * "aws_attributes": { "availability": "SPOT", "zone_id": "us-west-2a" },
-     * "num_workers": 25 } See below as an example for an autoscaling cluster.
-     * Note that this cluster will start with `2` nodes, the minimum. .. code:: {
-     * "cluster_name": "autoscaling-cluster", "spark_version": "2.0.x-scala2.10",
-     * "node_type_id": "r3.xlarge", "autoscale" : { "min_workers": 2,
-     * "max_workers": 50 } }
+     * an informative error message.
      */
     async create(
         request: model.CreateCluster,
@@ -128,11 +128,12 @@ export class ClustersService {
     }
 
     /**
-     * Terminates a Spark cluster given its id. The cluster is removed
+     * Terminate cluster
+     *
+     * Terminates the Spark cluster with the specified ID. The cluster is removed
      * asynchronously. Once the termination has completed, the cluster will be in
      * a ``TERMINATED`` state. If the cluster is already in a ``TERMINATING`` or
-     * ``TERMINATED`` state, nothing will happen. An example request: .. code:: {
-     * "cluster_id": "1202-211320-brick1" }
+     * ``TERMINATED`` state, nothing will happen.
      */
     async delete(
         request: model.DeleteCluster,
@@ -201,17 +202,21 @@ export class ClustersService {
     }
 
     /**
-     * Edits the configuration of a cluster to match the provided attributes and
-     * size. A cluster can be edited if it is in a ``RUNNING`` or ``TERMINATED``
-     * state. If a cluster is edited while in a ``RUNNING`` state, it will be
-     * restarted so that the new attributes can take effect. If a cluster is
-     * edited while in a ``TERMINATED`` state, it will remain ``TERMINATED``. The
-     * next time it is started using the ``clusters/start`` API, the new
-     * attributes will take effect. An attempt to edit a cluster in any other
-     * state will be rejected with an ``INVALID_STATE`` error code. Clusters
-     * created by the Databricks Jobs service cannot be edited. An example
-     * request: .. code:: { "cluster_id": "1202-211320-brick1", "num_workers":
-     * 10, "spark_version": "3.3.x-scala2.11", "node_type_id": "i3.2xlarge" }
+     * Update cluster configuration
+     *
+     * Updates the configuration of a cluster to match the provided attributes
+     * and size. A cluster can be updated if it is in a ``RUNNING`` or
+     * ``TERMINATED`` state.
+     *
+     * If a cluster is updated while in a ``RUNNING`` state, it will be restarted
+     * so that the new attributes can take effect.
+     *
+     * If a cluster is updated while in a ``TERMINATED`` state, it will remain
+     * ``TERMINATED``. The next time it is started using the ``clusters/start``
+     * API, the new attributes will take effect. Any attempt to update a cluster
+     * in any other state will be rejected with an ``INVALID_STATE`` error code.
+     *
+     * Clusters created by the Databricks Jobs service cannot be edited.
      */
     async edit(
         request: model.EditCluster,
@@ -280,20 +285,11 @@ export class ClustersService {
     }
 
     /**
+     * List cluster activity events
+     *
      * Retrieves a list of events about the activity of a cluster. This API is
      * paginated. If there are more events to read, the response includes all the
-     * parameters necessary to request the next page of events. An example
-     * request: ``/clusters/events?cluster_id=1202-211320-brick1`` An example
-     * response: { "events": [ { "cluster_id": "1202-211320-brick1", "timestamp":
-     * 1509572145487, "event_type": "RESTARTING", "event_details": { "username":
-     * "admin" } }, ... { "cluster_id": "1202-211320-brick1", "timestamp":
-     * 1509505807923, "event_type": "TERMINATING", "event_details": {
-     * "termination_reason": { "code": "USER_REQUEST", "parameters": [
-     * "username": "admin" ] } } ], "next_page": { "cluster_id":
-     * "1202-211320-brick1", "end_time": 1509572145487, "order": "DESC",
-     * "offset": 50 }, "total_count": 303 } Example request to retrieve the next
-     * page of events
-     * ``/clusters/events?cluster_id=1202-211320-brick1&end_time=1509572145487&order=DESC&offset=50``
+     * nparameters necessary to request the next page of events.
      */
     async events(
         request: model.GetEvents,
@@ -309,10 +305,11 @@ export class ClustersService {
     }
 
     /**
-     * Retrieves the information for a cluster given its identifier. Clusters can
-     * be described while they are running, or up to 60 days after they are
-     * terminated. An example request:
-     * ``/clusters/get?cluster_id=1202-211320-brick1``
+     * Get cluster info
+     *
+     * "Retrieves the information for a cluster given its identifier. Clusters
+     * can be described while they are running, or up to 60 days after they are
+     * terminated.
      */
     async get(
         request: model.GetRequest,
@@ -381,14 +378,18 @@ export class ClustersService {
     }
 
     /**
+     * List all clusters
+     *
      * Returns information about all pinned clusters, currently active clusters,
      * up to 70 of the most recently terminated interactive clusters in the past
      * 7 days, and up to 30 of the most recently terminated job clusters in the
-     * past 7 days. For example, if there is 1 pinned cluster, 4 active clusters,
-     * 45 terminated interactive clusters in the past 7 days, and 50 terminated
-     * job clusters in the past 7 days, then this API returns the 1 pinned
-     * cluster, 4 active clusters, all 45 terminated interactive clusters, and
-     * the 30 most recently terminated job clusters.
+     * past 7 days.
+     *
+     * For example, if there is 1 pinned cluster, 4 active clusters, 45
+     * terminated interactive clusters in the past 7 days, and 50 terminated job
+     * clusters\nin the past 7 days, then this API returns the 1 pinned cluster,
+     * 4 active clusters, all 45 terminated interactive clusters, and the 30 most
+     * recently terminated job clusters.
      */
     async list(
         request: model.ListRequest,
@@ -404,6 +405,8 @@ export class ClustersService {
     }
 
     /**
+     * List node types
+     *
      * Returns a list of supported Spark node types. These node types can be used
      * to launch a cluster.
      */
@@ -420,8 +423,10 @@ export class ClustersService {
     }
 
     /**
-     * Returns a list of availability zones where clusters can be created in (ex:
-     * us-west-2a). These zones can be used to launch a cluster.
+     * List availability zones
+     *
+     * Returns a list of availability zones where clusters can be created in (For
+     * example, us-west-2a). These zones can be used to launch a cluster.
      */
     async listZones(
         cancellationToken?: CancellationToken
@@ -436,11 +441,14 @@ export class ClustersService {
     }
 
     /**
+     * Permanently delete cluster
+     *
      * Permanently deletes a Spark cluster. This cluster is terminated and
-     * resources are asynchronously removed. In addition, users will no longer
-     * see permanently deleted clusters in the cluster list, and API users can no
-     * longer perform any action on permanently deleted clusters. An example
-     * request: .. code:: { "cluster_id": "1202-211320-brick1" }
+     * resources are asynchronously removed.
+     *
+     * In addition, users will no longer see permanently deleted clusters in the
+     * cluster list, and API users can no longer perform any action on
+     * permanently deleted clusters.
      */
     async permanentDelete(
         request: model.PermanentDeleteCluster,
@@ -456,10 +464,11 @@ export class ClustersService {
     }
 
     /**
+     * Pin cluster
+     *
      * Pinning a cluster ensures that the cluster will always be returned by the
      * ListClusters API. Pinning a cluster that is already pinned will have no
-     * effect. This API can only be called by workspace admins. An example
-     * request: ``/clusters/pin?cluster_id=1202-211320-brick1``
+     * effect. This API can only be called by workspace admins.
      */
     async pin(
         request: model.PinCluster,
@@ -475,9 +484,10 @@ export class ClustersService {
     }
 
     /**
+     * Resize cluster
+     *
      * Resizes a cluster to have a desired number of workers. This will fail
-     * unless the cluster is in a ``RUNNING`` state. An example request: ..
-     * code:: { "cluster_id": "1202-211320-brick1", "num_workers": 30 }
+     * unless the cluster is in a `RUNNING` state.
      */
     async resize(
         request: model.ResizeCluster,
@@ -546,9 +556,10 @@ export class ClustersService {
     }
 
     /**
-     * Restarts a Spark cluster given its id. If the cluster is not currently in
-     * a ``RUNNING`` state, nothing will happen. An example request: .. code:: {
-     * "cluster_id": "1202-211320-brick1" }
+     * Restart cluster
+     *
+     * Restarts a Spark cluster with the supplied ID. If the cluster is not
+     * currently in a `RUNNING` state, nothing will happen.
      */
     async restart(
         request: model.RestartCluster,
@@ -617,6 +628,8 @@ export class ClustersService {
     }
 
     /**
+     * List available Spark versions
+     *
      * Returns the list of available Spark versions. These versions can be used
      * to launch a cluster.
      */
@@ -633,14 +646,16 @@ export class ClustersService {
     }
 
     /**
-     * Starts a terminated Spark cluster given its id. This works similar to
-     * `createCluster` except: - The previous cluster id and attributes are
-     * preserved. - The cluster starts with the last specified cluster size. - If
-     * the previous cluster was an autoscaling cluster, the current cluster
-     * starts with the minimum number of nodes. - If the cluster is not currently
-     * in a ``TERMINATED`` state, nothing will happen. - Clusters launched to run
-     * a job cannot be started. An example request: .. code:: { "cluster_id":
-     * "1202-211320-brick1" }
+     * Start terminated cluster
+     *
+     * Starts a terminated Spark cluster with the supplied ID. This works similar
+     * to `createCluster` except:
+     *
+     * * The previous cluster id and attributes are preserved. * The cluster
+     * starts with the last specified cluster size. * If the previous cluster was
+     * an autoscaling cluster, the current cluster starts with the minimum number
+     * of nodes. * If the cluster is not currently in a ``TERMINATED`` state,
+     * nothing will happen. * Clusters launched to run a job cannot be started.
      */
     async start(
         request: model.StartCluster,
@@ -709,10 +724,11 @@ export class ClustersService {
     }
 
     /**
+     * Unpin cluster
+     *
      * Unpinning a cluster will allow the cluster to eventually be removed from
      * the ListClusters API. Unpinning a cluster that is not pinned will have no
-     * effect. This API can only be called by workspace admins. An example
-     * request: ``/clusters/unpin?cluster_id=1202-211320-brick1``
+     * effect. This API can only be called by workspace admins.
      */
     async unpin(
         request: model.UnpinCluster,