server/console/docs: add a comment field for actions

####  CHANGELOG (done)

#### PR description

This PR hopes to resolve https://github.com/hasura/graphql-engine/issues/4662.
The main work done in this PR is to add an comment field on the add actions page. Prior to this the `actionsDescription` was used as the comment for actions.

#### Updated UI

![image](https://user-images.githubusercontent.com/6604943/111342362-64dc9880-86a0-11eb-8922-36b72bf100cb.png)

Co-authored-by: Aleksandra Sikora <9019397+beerose@users.noreply.github.com>
GitOrigin-RevId: 5f31b27d66c27bc6c1b0fc5044f0ac13ecc11fa0

CHANGELOG.md

@@ -3,6 +3,9 @@
 ## Next release
 (Add entries here in the order of: server, console, cli, docs, others)
 
+- server: add a comment field for actions (#231)
+- console: add a comment field for actions (#231)
+
 ### Support geometry and geography spatial data comparison operators in MS SQL Server
 
 Comparison operators on spatial data types, geometry and geography, are now supported in MS SQL Server. The following operators are supported:

console/src/components/Services/Actions/Actions.scss

@@ -323,4 +323,8 @@
 .listItems {
   display: flex;
   align-items: center;
-}
+}
+
+.comment_container_styles {
+  width: 26%;
+}

console/src/components/Services/Actions/Add/Add.js

@@ -1,5 +1,6 @@
 import React, { useEffect } from 'react';
-import styles from './Styles.scss';
+import actionStyles from '../Actions.scss';
+import styles from '../../../Common/Common.scss';
 import Helmet from 'react-helmet';
 import HandlerEditor from '../Common/components/HandlerEditor';
 import KindEditor from '../Common/components/KindEditor';
@@ -14,6 +15,7 @@ import {
   setHeaders as dispatchNewHeaders,
   toggleForwardClientHeaders as toggleFCH,
   resetDerivedActionParentOperation,
+  setActionComment,
 } from './reducer';
 import { createAction } from '../ServerIO';
 import { getActionDefinitionFromSdl } from '../../../../shared/utils/sdlUtils';
@@ -39,6 +41,7 @@ const AddAction = ({
   forwardClientHeaders,
   derive,
   readOnlyMode,
+  comment,
 }) => {
   useEffect(() => {
     if (readOnlyMode)
@@ -59,6 +62,7 @@ const AddAction = ({
 
   const handlerOnChange = e => dispatch(setActionHandler(e.target.value));
   const kindOnChange = k => dispatch(setActionKind(k));
+  const commentOnChange = e => dispatch(setActionComment(e.target.value));
 
   const {
     sdl: typesDefinitionSdl,
@@ -113,7 +117,7 @@ const AddAction = ({
 
   return (
     <div>
-      <Helmet title={'Add Action - Actions | Hasura'} />
+      <Helmet title="Add Action - Actions | Hasura" />
       <h2
         className={`${styles.headerText} ${styles.display_inline} ${styles.add_mar_bottom_mid}`}
       >
@@ -140,6 +144,22 @@ const AddAction = ({
         allowEmpty
       />
       <hr />
+      <div className={actionStyles.comment_container_styles}>
+        <h2
+          className={`${styles.subheading_text} ${styles.add_mar_bottom_small}`}
+        >
+          Comment
+        </h2>
+        <input
+          disabled={readOnlyMode}
+          type="text"
+          value={comment}
+          onChange={commentOnChange}
+          placeholder="comment"
+          className={`form-control ${styles.inputWidthLarge}`}
+        />
+      </div>
+      <hr />
       <HandlerEditor
         value={handler}
         onChange={handlerOnChange}

console/src/components/Services/Actions/Add/Styles.scss

@@ -1 +0,0 @@
-@import '../../../Common/Common.scss';

console/src/components/Services/Actions/Add/reducer.js

@@ -15,6 +15,12 @@ export const setActionKind = kind => ({
   kind,
 });
 
+const SET_ACTION_COMMENT = 'Actions/Add/SET_ACTION_COMMENT';
+export const setActionComment = comment => ({
+  type: SET_ACTION_COMMENT,
+  comment,
+});
+
 const SET_ACTION_DEFINITION = 'Actions/Add/SET_ACTION_DEFINITION';
 export const setActionDefinition = (sdl, error = null, timer, ast) => ({
   type: SET_ACTION_DEFINITION,
@@ -71,6 +77,11 @@ const reducer = (state = defaultState, action) => {
         ...state,
         kind: action.kind,
       };
+    case SET_ACTION_COMMENT:
+      return {
+        ...state,
+        comment: action.comment,
+      };
     case SET_FETCHING:
       return {
         ...state,

console/src/components/Services/Actions/Add/state.js

@@ -38,6 +38,7 @@ const state = {
   derive: {
     operation: '',
   },
+  comment: '',
 };
 
 export default state;

console/src/components/Services/Actions/Common/components/HandlerEditor.js

@@ -23,7 +23,7 @@ const HandlerEditor = ({ value, onChange, className, disabled = false }) => {
         type="text"
         value={value}
         onChange={onChange}
-        placeholder={'http://custom-logic.com/api'}
+        placeholder="http://custom-logic.com/api"
         className={`form-control ${styles.inputWidthLarge}`}
         data-test="action-create-handler-input"
       />

console/src/components/Services/Actions/Modify/ActionEditor.js

@@ -1,5 +1,6 @@
 import React from 'react';
-import styles from './Styles.scss';
+import styles from '../../../Common/Common.scss';
+import actionStyles from '../Actions.scss';
 import Helmet from 'react-helmet';
 import HandlerEditor from '../Common/components/HandlerEditor';
 import KindEditor from '../Common/components/KindEditor';
@@ -12,6 +13,7 @@ import {
   setActionKind,
   setActionDefinition,
   setTypeDefinition,
+  setActionComment,
   setHeaders as dispatchNewHeaders,
   toggleForwardClientHeaders as toggleFCH,
 } from './reducer';
@@ -37,7 +39,13 @@ const ActionEditor = ({
   readOnlyMode,
   ...modifyProps
 }) => {
-  const { handler, kind, actionDefinition, typeDefinition } = modifyProps;
+  const {
+    handler,
+    kind,
+    actionDefinition,
+    typeDefinition,
+    comment,
+  } = modifyProps;
 
   const {
     sdl: typesDefinitionSdl,
@@ -101,6 +109,9 @@ const ActionEditor = ({
     }
   }
 
+  const updateActionComment = e =>
+    dispatch(setActionComment(e.target.value?.trim()));
+
   return (
     <div>
       <Helmet title={`Modify Action - ${actionName} - Actions | Hasura`} />
@@ -125,6 +136,20 @@ const ActionEditor = ({
         allowEmpty
       />
       <hr />
+      <div className={actionStyles.comment_container_styles}>
+        <h2
+          className={`${styles.subheading_text} ${styles.add_mar_bottom_small}`}
+        >
+          Comment
+        </h2>
+        <input
+          type="text"
+          value={comment}
+          className={`form-control ${styles.inputWidthLarge}`}
+          onChange={updateActionComment}
+        />
+      </div>
+      <hr />
       <HandlerEditor
         value={handler}
         disabled={readOnlyMode}

console/src/components/Services/Actions/Modify/Main.js

@@ -2,23 +2,21 @@ import React from 'react';
 import ActionContainer from '../Containers/ActionContainer';
 import ActionEditor from './ActionEditor';
 
-const Modify = ({ params, allActions, allTypes, dispatch, ...modifyProps }) => {
-  return (
-    <ActionContainer
-      params={params}
+const Modify = ({ params, allActions, allTypes, dispatch, ...modifyProps }) => (
+  <ActionContainer
+    params={params}
+    allActions={allActions}
+    tabName="modify"
+    dispatch={dispatch}
+  >
+    <ActionEditor
       allActions={allActions}
-      tabName="modify"
+      allTypes={allTypes}
       dispatch={dispatch}
-    >
-      <ActionEditor
-        allActions={allActions}
-        allTypes={allTypes}
-        dispatch={dispatch}
-        actionName={params.actionName}
-        {...modifyProps}
-      />
-    </ActionContainer>
-  );
-};
+      actionName={params.actionName}
+      {...modifyProps}
+    />
+  </ActionContainer>
+);
 
 export default Modify;

console/src/components/Services/Actions/Modify/Styles.scss

@@ -1 +0,0 @@
-@import '../../../Common/Common.scss';

console/src/components/Services/Actions/Modify/reducer.js

@@ -18,6 +18,12 @@ export const setActionKind = kind => ({
   kind,
 });
 
+const SET_ACTION_COMMENT = 'Actions/Modify/SET_ACTION_COMMENT';
+export const setActionComment = comment => ({
+  type: SET_ACTION_COMMENT,
+  comment,
+});
+
 const SET_ACTION_DEFINITION = 'Actions/Modify/SET_ACTION_DEFINITION';
 export const setActionDefinition = (sdl, error, timer, ast) => ({
   type: SET_ACTION_DEFINITION,
@@ -63,6 +69,11 @@ const reducer = (state = defaultState, action) => {
         ...state,
         kind: action.kind,
       };
+    case SET_ACTION_COMMENT:
+      return {
+        ...state,
+        comment: action.comment,
+      };
     case SET_FETCHING:
       return {
         ...state,

console/src/components/Services/Actions/Modify/state.js

@@ -14,6 +14,7 @@ const state = {
   isFetching: false,
   headers: [defaultHeader],
   forwardClientHeaders: false,
+  comment: '',
 };
 
 export default state;

console/src/components/Services/Actions/Modify/utils.js

@@ -34,6 +34,7 @@ export const getModifyState = (currentAction, allTypes) => {
     kind: actionDef.kind,
     headers: parseServerHeaders(actionDef.headers),
     forwardClientHeaders: actionDef.forward_client_headers,
+    comment: currentAction.comment,
   };
   return modifyState;
 };

console/src/components/Services/Actions/ServerIO.js

@@ -64,12 +64,14 @@ export const createAction = () => (dispatch, getState) => {
   const { add: rawState } = getState().actions;
   const existingTypesList = customTypesSelector(getState());
   const allActions = actionsSelector(getState());
+
+  const actionComment = rawState.comment ? rawState.comment.trim() : null;
+
   const {
     name: actionName,
     arguments: args,
     outputType,
     error: actionDefError,
-    comment: actionDescription,
     type: actionType,
   } = getActionDefinitionFromSdl(rawState.actionDefinition.sdl);
   if (actionDefError) {
@@ -98,7 +100,7 @@ export const createAction = () => (dispatch, getState) => {
     outputType,
     headers: rawState.headers,
     forwardClientHeaders: rawState.forwardClientHeaders,
-    comment: actionDescription,
+    comment: actionComment,
   };
 
   const validationError = getStateValidationError(state, existingTypesList);
@@ -142,7 +144,7 @@ export const createAction = () => (dispatch, getState) => {
   const actionQueryUp = generateCreateActionQuery(
     state.name,
     generateActionDefinition(state),
-    actionDescription
+    actionComment
   );
 
   const actionQueryDown = generateDropActionQuery(state.name);
@@ -192,7 +194,6 @@ export const saveAction = currentAction => (dispatch, getState) => {
     outputType,
     type: actionType,
     error: actionDefError,
-    comment: actionDescription,
   } = getActionDefinitionFromSdl(rawState.actionDefinition.sdl);
 
   if (actionDefError) {
@@ -201,6 +202,8 @@ export const saveAction = currentAction => (dispatch, getState) => {
     );
   }
 
+  const actionComment = rawState.comment ? rawState.comment.trim() : null;
+
   const { types, error: typeDefError } = getTypesFromSdl(
     rawState.typeDefinition.sdl
   );
@@ -220,7 +223,7 @@ export const saveAction = currentAction => (dispatch, getState) => {
     outputType,
     headers: rawState.headers,
     forwardClientHeaders: rawState.forwardClientHeaders,
-    comment: actionDescription,
+    comment: actionComment,
   };
 
   const validationError = getStateValidationError(state);
@@ -254,7 +257,7 @@ export const saveAction = currentAction => (dispatch, getState) => {
   const updateCurrentActionQuery = getUpdateActionQuery(
     generateActionDefinition(state),
     currentAction.name,
-    actionDescription
+    actionComment
   );
   const rollbackActionQuery = getUpdateActionQuery(
     currentAction.definition,
@@ -265,7 +268,7 @@ export const saveAction = currentAction => (dispatch, getState) => {
   const createNewActionQuery = generateCreateActionQuery(
     state.name,
     generateActionDefinition(state),
-    actionDescription
+    actionComment
   );
 
   const actionQueryDown = generateDropActionQuery(state.name);

docs/graphql/core/api-reference/schema-metadata-api/actions.rst

@@ -167,7 +167,8 @@ Update an action ``create_user`` by making it's kind to ``asynchronous``:
             ],
             "output_type":"User",
             "handler":"https://action.my_app.com/create-user"
-         }
+         },
+         "comment": "Custom action to create user",
       }
    }
 
@@ -192,6 +193,10 @@ Args syntax
      - true
      - :ref:`ActionDefinition`
      - Definition of the action to be replaced
+   * - comment
+     - false
+     - text
+     - comment
 
 .. _create_action_permission:
 

server/src-lib/Hasura/RQL/DDL/Action.hs

@@ -123,15 +123,18 @@ resolveAction env AnnotatedCustomTypes{..} ActionDefinition{..} allScalars = do
 runUpdateAction
   :: forall m. ( QErrM m , CacheRWM m, MetadataM m)
   => UpdateAction -> m EncJSON
-runUpdateAction (UpdateAction actionName actionDefinition) = do
+runUpdateAction (UpdateAction actionName actionDefinition actionComment) = do
   sc <- askSchemaCache
   let actionsMap = scActions sc
   void $ onNothing (Map.lookup actionName actionsMap) $
     throw400 NotExists $ "action with name " <> actionName <<> " not exists"
-  buildSchemaCacheFor (MOAction actionName)
-    $ MetadataModifier
-    $ metaActions.ix actionName.amDefinition .~ actionDefinition
+  buildSchemaCacheFor (MOAction actionName) $ updateActionMetadataModifier actionDefinition actionComment
   pure successMsg
+    where
+      updateActionMetadataModifier :: ActionDefinitionInput -> Maybe Text -> MetadataModifier
+      updateActionMetadataModifier def comment = MetadataModifier $
+        (metaActions.ix actionName.amDefinition .~ def) .
+        (metaActions.ix actionName.amComment .~ comment)
 
 newtype ClearActionData
   = ClearActionData { unClearActionData :: Bool }

server/src-lib/Hasura/RQL/Types/Action.hs

@@ -230,6 +230,7 @@ data UpdateAction
   = UpdateAction
   { _uaName       :: !ActionName
   , _uaDefinition :: !ActionDefinitionInput
+  , _usComment    :: !(Maybe Text)
   } deriving (Show, Eq)
 $(J.deriveJSON hasuraJSON ''UpdateAction)