SAM local API: "long lived" (server / daemon) mode
- Dominant language
- TypeScript
- Stars
- 2k
- Forks
- 807
- Avg merge
- 10h 12m
- Merged PRs (30d)
- 7
Description
## Problem
When local invoking a APIGateway Lambda, the Toolkit always started the local api only for the lifetime of the request or debug session. Customers may want the API to stay running so they can make other requests (for example via `curl`, postman, [vscode-restclient](https://github.com/Huachao/vscode-restclient), ...).
## Use cases
* Want to use a desktop application or arbitrary REST/HTTP client (postman, `curl`, ...) to send requests to the local API endpoint.
* Don't want to craft different launch configs to make requests.
* Avoids mounting Docker image on each request (minor performance benefit).
## Expected behavior
1. User can run the `AWS: Start Local API` command to start a local API.
1. Toolkit does not stop the local API, it continues running until
* vscode terminates
* user re-runs `AWS: Start Local API`
* user runs `AWS: Stop Local API`
1. Toolkit tracks the APIs it has started.
1. AWS “Local Explorer” shows a list of local endpoints.
1. Endpoint context menu:
1. `Stop`
1. `Copy URL`
1. `Send request` (?)
1. When the Lambda code changes, Toolkit restarts the local API. (?)
1. When vscode terminates, Toolkit prompts to stop any running local APIs (that it started).
### Attach to an already-running local API
Requested in https://github.com/aws/aws-toolkit-vscode/issues/2455#issuecomment-1085024260 :
1. While a `sam local start-api` endpoint is already running... :
1. Introduce this `invokeTarget.type = "api"` variant:
- no `logicalId`, `api`, `payload`
- This launch config is purely to _attach_. It doesn't _request_. (Do we even _need_ a launch config?)
1. User can run `AWS: Debug Local API` to attach to an already running `start-api`
- Toolkit lists all local API endpoints (impl: `docker ps` ?) ?
- User chooses an endpoint + port
- User chooses a [coderoot](https://github.com/aws/aws-toolkit-vscode/blob/2f7a03f33e175482399fbe9f7541b1e168a124c4/src/shared/sam/debugger/typescriptSamDebug.ts#L101) or [pathmapping](https://github.com/aws/aws-toolkit-vscode/blob/2f7a03f33e175482399fbe9f7541b1e168a124c4/src/shared/sam/debugger/pythonSamDebug.ts#L207)
1. Toolkit attaches vscode debugger
1. *User calls the endpoint using `curl` or a REST/HTTP client...*
1. vscode debugger session begins
Contributor guide
Research direction
Start with the AWS: Start Local API, AWS: Stop Local API, AWS: Debug Local API, and Local Explorer entry points, then review the referenced typescriptSamDebug.ts and pythonSamDebug.ts files. Trace how local APIs are started, tracked, stopped, and discovered, including the docker ps question. Done means the requested persistent API lifecycle, endpoint actions, restart behavior, shutdown prompt, and optional debugger attachment are defined and covered by tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, docker, typescript, vscode
- Domain
- api, developer-experience, devtools
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100