Merge branch 'main' into pre-pg-proc-refacting

Author: gledis69

docs/internals/StoredProcedureDesignDoc.md

@@ -2,7 +2,7 @@
 
 ## Design/Spec Summary
 ### Entity Source Object Config
-Currently, the `source` attribute is always a string. With the addition of stored procedure support and the next version of the JSON schema: [here](https://github.com/Azure/project-hawaii/blob/db619b4175719c83d540bc30ef5acc5faa6faa6d/playground/hawaii.draft-02.schema.json), the `source` attribute is now optionally an object with attributes like so:
+Currently, the `source` attribute is always a string. With the addition of stored procedure support and the next version of the JSON schema: [here](https://dataapibuilder.azureedge.net/schemas/v0.4.11-alpha/dab.draft.schema.json), the `source` attribute is now optionally an object with attributes like so:
 ```json
 "type": {
     "type": "string",                                            
@@ -51,21 +51,23 @@ parameters can either be fixed as above or passed at runtime through
 
 ### Stored Procedure Permissions 
 
-Stored procedures have identical role/action permissions to any other entity. i.e. same familiar format:
+Stored procedure backed entities have similar role/action permissions to other entities. i.e. same familiar format:
+
 ```json
 "permissions": [
         {
             "role": "anonymous",
-            "actions": [ "read" ]
+            "actions": [ "execute" ]
 
         },
         {
             "role": "authenticated",
-            "actions": [ "create" ]
+            "actions": [ "execute" ]
         }
 ]
-``` 
-However, the behavior of **column/field-level permissions** and **database policies** have not yet been designed/defined for procedures; as such, these will be **ignored**.
+```
+
+However, stored procedures only accept the action **execute**. **Column/field-level permissions** and **database policies** are not supported.
 
 <a id='suggested-config'></a>
 > Why not simplify stored procedure permissions, if POST, PUT, PATCH, DELETE semantically identical?
@@ -75,6 +77,7 @@ Justification **against** supporting all CRUD operations:
 - Other solutions usually limit to `POST`: https://learn.microsoft.com/rest/api/cosmos-db/execute-a-stored-procedure
     - [PostgREST](https://postgrest.org/en/stable/api.html#stored-procedures) support `POST` and `GET` if marked `IMMUTABLE` or `STABLE`
 - Proposed permission:
+
 ```json
 "permissions": [
         {
@@ -87,11 +90,13 @@ Justification **against** supporting all CRUD operations:
         }
 ]
 ```
+
 Justification **for** allowing permission configuration for all CRUD operations:
+
 - Davide: the "simplification" would complicate authorization with no real benefit. True in that the authorization logic would need to change conditioned on whether the entity source was a stored procedure.
-- Aniruddh: we should leave the responsibility for the developer to properly configure hawaii; it's not our fault if they configure against the API guidelines
+- Aniruddh: we should leave the responsibility for the developer to properly configure Data API Builder; it's not our fault if they configure against the API guidelines
 
-Users can provide only one CRUD operation for stored-procedure. 
+Users can provide only one CRUD operation for stored-procedure.
 CREATE/UPDATE/DELETE(CUD) action will create mutation operation, while READ will create a Query operation for GraphQL.
 Providing more than one (CRUD) operation would throw an error and the engine will fail to start during initialization.
 

docs/views-and-stored-procedures.md

@@ -48,7 +48,7 @@ Stored procedures can be used as objects related to entities exposed by Data API
 If you have a stored procedure, for example [`dbo.stp_get_all_cowritten_books_by_author`](../samples/getting-started/azure-sql-db/library.azure-sql.sql#L138) it can be exposed using the following `dab` command:
 
 ```sh
-dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" source.params "searchType:s" --permissions "anonymous:read" --rest true --graphql true
+dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "get" --graphql.operation "query"
 ```
 
 the `dab-config.json` file will look like the following:
@@ -62,47 +62,127 @@ the `dab-config.json` file will look like the following:
       "searchType": "s"
     }
   },
-  "rest": true,
-  "graphql": true,
+  "rest": {
+    "methods": [ "GET" ]
+  },
+  "graphql": {
+    "operation": "query"
+  },
   "permissions": [{
    "role": "anonymous",
-    "actions": [ "read" ]
+    "actions": [ "execute" ]
   }]
 }
 ```
 
 The `parameters` defines which parameters should be exposed and to provide default values to be passed to the stored procedure parameters, if those are not provided in the HTTP request.
 
-**ATTENTION**:
+**Limitations**:
 
 1. Only the first result set returned by the stored procedure will be used by Data API Builder.
-1. If more than one CRUD action is specified in the config, runtime initialization will fail due to config validation error.
-
-Please note that **you should configure the permission accordingly with the stored procedure behavior**. For example, if a Stored Procedure create a new item in the database, it is recommended to allow only the action `create` for such stored procedure. If, like in the sample, a stored procedure returns some data, it is recommended to allow only the action `read`. In general the recommendation is to align the allowed actions to what the stored procedure does, so to provide a consistent experience to the developer.
+2. For both REST and GraphQL endpoints: when a stored procedure parameter is specified both in the configuration file and in the URL query string, the parameter in the URL query string will take precedence.
+3. Entities backed by a stored procedure do not have all the capabilities automatically provided for entities backed by tables, collections or views. Stored procedure backed entities do not support pagination, ordering, or filtering. Nor do such entities support returning items specified by primary key values.
 
 ### REST support for stored procedures
 
-Entities backed by a stored procedure, do not have all the capabilities automatically provided for entities backed by tables, collections or views. An entity using a stored procedure will not have support for pagination, ordering, filtering or for returning an item by specifying the primary key values.
+The REST endpoint behavior for a stored procedure backed entity can be configured to be available for one or multiple HTTP verbs (GET, POST, PUT, PATCH, DELETE). The REST section of the entity would look like the following:
+
+```json
+"rest": {
+  "methods": [ "GET", "POST" ]
+}
+```
+
+Any REST requests for the entity will fail with **HTTP 405 Method Not Allowed** when an HTTP method not listed in the configuration is used. e.g. executing a PUT request will fail with error code 405.
+If the `methods` section is excluded from the entity's REST configuration, the default method **POST** will be inferred. To disable the REST endpoint for this entity, configure `"rest": false` and any REST requests on the stored procedure entity will fail with **HTTP 404 Not Found**.
 
 If the stored procedure accepts parameters, those can be passed in the URL query string when calling the REST endpoint. For example:
 
 ```text
 http://<dab-server>/api/GetCowrittenBooksByAuthor?author=isaac%20asimov
 ```
 
-If a parameter is specified both in the configuration file and in the URL query string, the one in the URL query string will take precedence.
-
 ### GraphQL support for stored procedures
 
-Just like for REST, entities backed by a stored procedure, do not have all the capabilities automatically provided for entities backed by tables, collections or views. An entity using a stored procedure will not have support for pagination, ordering, filtering or for returning an item by specifying the primary key values.
+Stored procedure execution in GraphQL can be configured using the `graphql` option of a stored procedure backed entity. Explicitly setting the operation of the entity allows you to represent a stored procedure in the GraphQL schema in a way that aligns with the behavior of the stored procedure.
+Not setting any value for the operation will result in the creation of a `mutation` operation.
+
+For example, using the value `query` for the `operation` option results in the stored procedure resolving as a query field in the GraphQL schema
+
+CLI Usage:
+
+```sh
+dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "GET" --graphql.operation "query"
+```
+
+Runtime Configuration:
+
+```json
+"graphql": {
+  "operation": "query"
+}
+```
+
+GraphQL Schema Components: type and query field:
+
+```graphql
+type GetCowrittenBooksByAuthor {
+  id: Int!
+  title: String
+}
+
+In the schema, both query and mutation operations for stored procedures will have `execute` as a prefix. For the above stored procedure the exact query name field generated would be `executeGetCowrittenBooksByAuthor`
+
+type Query {
+  """
+  Execute Stored-Procedure GetCowrittenBooksByAuthor and get results from the database
+  """
+  executeGetCowrittenBooksByAuthor(
+    """
+    parameters for GetCowrittenBooksByAuthor stored-procedure
+    """
+    searchType: String = "S"
+  ): [GetCowrittenBooksByAuthor!]!
+}
+```
+
+Alternatively, `operation` can be set to `mutation` so that a mutation field represents the stored procedure in the GraphQL schema. The below `dab update` command can be used to change the `operation`:
+
+```sh
+dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"
+```
+
+Runtime configuration:
+
+```json
+"graphql": {
+  "operation": "mutation"
+}
+```
+GraphQL Schema Components: type and mutation field:
+
+type Mutation {
+  type GetCowrittenBooksByAuthor {
+    id: Int!
+    title: String
+  }
 
-Depending on the `action` defined in the configuration file a GraphQL query object will be generated - if `read` action has been specified - or a mutation object will be created - if `create`, `update` or `delete` action has been specified.
+  """
+  Execute Stored-Procedure GetCowrittenBooksByAuthor and get results from the database
+  """
+  executeGetCowrittenBooksByAuthor(
+    """
+    parameters for GetCowrittenBooksByAuthor stored-procedure
+    """
+    searchType: String = "S"
+  ): [GetCowrittenBooksByAuthor!]!
+}
 
 If the stored procedure accepts parameters, those can be passed as parameter of the query or mutation. For example:
 
 ```graphql
 query {
-  GetCowrittenBooksByAuthor(author:"asimov")
+  executeGetCowrittenBooksByAuthor(author:"asimov")
    {
     id
     title
@@ -111,5 +191,3 @@ query {
   }
 }
 ```
-
-If a parameter is specified both in the configuration file and in the URL query string for a stored procedure, the one in the URL query string will take precedence.

src/Cli/src/ConfigGenerator.cs

@@ -1009,7 +1009,6 @@ private static bool TryAddGraphQLOperationForDatabaseExecutable(EntityOptions op
         /// RestDatabaseExecutableEntityVerboseSettings-> when a stored procedure entity/function is configured with explicit RestMethods and Path settings.</returns>
         private static object? ConstructUpdatedRestDetails(Entity entity, EntityOptions options)
         {
-
             // Updated REST Route details
             object? restPath = (options.RestRoute is not null) ? ConstructRestPathDetails(options.RestRoute) : entity.GetRestEnabledOrPathSettings();
 
@@ -1106,7 +1105,11 @@ private static bool TryAddGraphQLOperationForDatabaseExecutable(EntityOptions op
                 }
                 else
                 {
-                    if (options.GraphQLOperationForDatabaseExecutable is not null)
+                    if (options.GraphQLOperationForDatabaseExecutable is null)
+                    {
+                        graphQLOperation = null;
+                    }
+                    else
                     {
                         graphQLType = null;
                     }

src/Cli/src/Utils.cs

@@ -93,9 +93,9 @@ public static string GetProductVersion()
             // definitions and with/without a custom graphQL type definition.
             else if (graphQLDetail is not null && graphQLOperation is null)
             {
-                if (graphQLDetail is true || graphQLDetail is false)
+                if (graphQLDetail is bool graphQLEnabled)
                 {
-                    return graphQLDetail;
+                    return graphQLEnabled;
                 }
                 else
                 {
@@ -1006,14 +1006,13 @@ public static bool CheckConflictingGraphQLConfigurationForDatabaseExecutable(Ent
         public static object? ConstructGraphQLTypeDetails(string? graphQL)
         {
             object? graphQLType;
-            bool graphQLEnabled;
             if (graphQL is null)
             {
                 graphQLType = null;
             }
             else
             {
-                if (bool.TryParse(graphQL, out graphQLEnabled))
+                if (bool.TryParse(graphQL, out bool graphQLEnabled))
                 {
                     graphQLType = graphQLEnabled;
                 }