RFC - Local development and testing

Amplify CLI with the support of GraphQL transformer, makes it simple to develop a GraphQL API. To see this API in action, Amplify CLI requires customers to push to the cloud. Pushing changes to cloud is time consuming and makes iterative development & debugging less than ideal.

We are looking to support running AppSync APIs locally and make the iterative development-test-push processes faster. This RFC is a proposal for feedback on workflow and requirements as part of this effort. Please respond with any feedback on the current proposals or missing scenarios/ideas.

We propose adding new functionality to Amplify CLI, which is intended to provide the following functionality:
- Allow customer to run AppSync test server locally
- Detect changes to GraphQL schema and resolvers locally and hot-reload the server
- Run codegen to generate statements and types from the local server
- Generate configuration (for JavaScript, iOS, and Android platforms) files that include the local endpoint for AppSync service
- Host GraphiQL UI on the test server to play with API

## Example use case
The below example use case shows how local testing can be used. Let’s imagine a you have an Amplify Project initialized with React as front-end. You add a new API called MyGraphQLAPI:

```
$ amplify add api
? Please select from one of the below mentioned services (Use arrow keys)
❯ GraphQL
? Please select from one of the below mentioned services GraphQL
? Provide API name: MyGraphQLAPI
? Choose an authorization type for the API: API key
? Do you have an annotated GraphQL schema? No
? Do you want a guided schema creation? Yes
? What best describes your project: Single object with fields (e.g., “Todo” with ID, name, description)
? Do you want to edit the schema now? Yes
Please edit the file in your editor: ./amplify/backend/api/rds/schema.graphql
? Press enter to continue

GraphQL schema compiled successfully.
Edit your schema at ./amplify/backend/api/MyGraphQLAPI/schema.graphql
or place .graphql files in a directory at ./amplify/backend/api/MyGraphQLAPI/schema.graphql
Successfully added resource MyGraphQLAPI locally

Some next steps:
"amplify test api " (or some similar command that might be implicit in the push flow) will run AppSync test server locally on your machine and allow you to
play with the GraphQL API
"amplify push" will build all your local backend resources and provision it
in the cloud
"amplify publish" will build all your local backend and frontend resources (if
you have hosting category added) and provision it in the cloud
```

Once the API is added, you can start the AppSync test server by running the following command. When there are resources other than GraphQL API in your project, those will be pushed to cloud first followed by starting AppSync test server.

```
$ amplify test api
Current Environment: dev


| Category | Resource name | Operation | Provider plugin |
| -------- | ------------- | --------- | ----------------- |
| Api | MyGraphQLAPI | Create | awscloudformation |
| Auth | cognito70e6 | Create | awscloudformation |


The following resources can not be tested locally

| Category | Resource name | Operation | Provider plugin |
| -------- | ------------- | --------- | ----------------- |
| Auth | cognito70e6 | Create | awscloudformation |

Do you want to push these resources to the cloud: Yes

UPDATE_IN_PROGRESS my-cool-project-dev-12222 AWS::CloudFormation::Stack Wed May 01 2019 11:40:26 GMT-0700 (Pacific Daylight Time) User Initiated
⠸ Updating resources in the cloud. This may take a few minutes...

CREATE_IN_PROGRESS cognito70e6 AWS::CloudFormation::Stack Wed May 01 2019 11:40:34 GMT-0700 (Pacific Daylight Time) Resource creation Initiated
CREATE_IN_PROGRESS cognito70e6 AWS::CloudFormation::Stack Wed May 01 2019 11:40:32 GMT-0700 (Pacific Daylight Time)
⠴ Updating resources in the cloud. This may take a few minutes...
...
...
...
...
⠦ Updating resources in the cloud. This may take a few minutes...
✔ All resources are updated in the cloud

? Do you want to generate code for your newly created GraphQL API: Yes
? Choose the code generation language target: javascript
? Enter the file name pattern of graphql queries, mutations and subscriptions: src/graphql/**/*.js
? Do you want to generate/update all possible GraphQL operations - queries, mutations and subscriptions: Yes
? Enter maximum statement depth [increase from default if your schema is deeply nested]: 2


Starting AppSync test server for MyGraphQLAPI
✔ GraphQL schema compiled successfully.
Edit your schema at ./amplify/backend/api/MyGraphQLAPI/schema.graphql
or place .graphql files in a directory at ./amplify/backend/api/MyGraphQLAPI/schema.graphql
Generating statements
Generating src/aws_exports.js
You can test your AppSync API by opening http://localhost:8090/
```

The AppSync test server will watch the schema and resolvers files for change and reload when it detects changes in any of these files. If there are errors in the schema or resolvers, those will be shown in the terminal

```
Change detected in ./amplify/backend/api/MyGraphQLAPI/schema.graphql
Rebuilding the schema using GraphQL transformer
✖ GraphQL schema failed to compile.
Edit your schema at ./amplify/backend/api/MyGraphQLAPI/schema.graphql or
place .graphql files in a directory at ./amplify/backend/api/MyGraphQLAPI/schema/
```

If the change did not have any error then then the server will reload with updated schema and resolvers
```
Change detected in ./amplify/backend/api/MyGraphQLAPI/schema.graphql
Rebuilding the schema using GraphQL transformer
✔GraphQL schema compiled successfully.
✔ Reloaded successfully.
```

### Auth support
The AppSync testing server will support API Key and Cognito user pools. Each request will have to either have `x-api-key` for API Key and `authorization` with JWT Token for Cognito User Pools. The JWT token has to be obtained from Cognito by either using ` Amplify.Auth.currentSession().getAccessToken().getJwtToken()` in Javascript or using `AWSMobileClient.getInstance().getTokens().getAccessToken().getTokenString()` in Android.

### VTL Error handling
AppSync local testing server watches the files the local file system and reloads the server when watched files changes. When the server reloads, it will parse all the VTL template and it will print an error in the console if there are an error in VTL template.

```
Change detected in ./amplify/backend/api/MyGraphQLAPI/resolvers/Mutation.addTodo.req.vtl
Error: Error parsing file amplif/backend/api/MyCoolAPI/resolvers/Mutation.addTodo.req.vtl
Lexical error on line 2. Unrecognized text.
...pochMilliSeconds())#set( $values = $ctx
----------------------^
✖ Reload failed
```

After fixing the VTL template error and saving the changes, AppSync test server will reload the template and if there are no further erros, the server will reload successfully.
```
Change detected in ./amplify/backend/api/MyGraphQLAPI/resolvers/Mutation.addTodo.req.vtl
✔ Reloaded successfully.
```

We plan to release a companion VSCode extension that can parse and show errors in the your VTL templates in the editor.

Please comment with any additional thoughts not covered in the above list. Thank you.