- Updated dependencies
- Updated
package.json
engines.node
property to reflect changes from v6
- Make a best effort attempt to terminate the process via
SIGINT
+SIGTERM
termination signals; should fix (or at least improve) #1479- Sandbox running via CLI will now forcefully terminate itself after 5 seconds if the termination routine has stalled out or takes too long
- Thanks @lpsinger + @courey!
- Updated dependencies
- Transitioned from
aws-sdk
toaws-lite
- Breaking change: Sandbox no longer includes
aws-sdk
+@aws-sdk/*
as dependencies; projects that rely on the AWS SDK should install those dependencies to their project directly - Breaking change:
nodejs20.x
andpython3.12
are now the default Node.js and Python Lambda runtimes, respectively - Breaking change: removed support for Node.js 14.x (now EOL, and no longer available to created in AWS Lambda)
- Added Node.js 20.x to test matrix
- Updated dependencies
- Updated dependencies
- Ensure
X-Forwarded-Port
header is always a string; thanks @lpsinger!
- Updated dependencies
- Ensure connected livereload clients are refreshed on all changes to
public/
- Updated dependencies
- Add coldstart simulator via
@sandbox coldstart true
setting inprefs.arc
- Note: Windows users must install
du
- Note: Windows users must install
- Fixed issue where qemu/emulator port conflicts were not detected with our open port tester; fixes 1441
- Added support for hydration of platform-specific binary deps (namely: Python); fixes #1457
- Minor improvements to Sandbox
@WS
API emulation - Added improvements to help output when port is in use; thanks @remysharp!
- Added error bubbling for the Sandbox plugin
invoke()
method; fixes #1447 - Added
@static prefix
setting support; fixes #1450
- Sandbox now cleans up per-Lambda vendor dirs (
node_modules
,vendor
) upon startup; fixes #1426- This can be disabled with
@sandbox delete-vendor false
preference or using the--disable-delete-vendor
flag
- This can be disabled with
- Updated dependencies
- Improved error handling during possible
@tables
port conflicts on startup; partially fixes #1441, thanks @jlipps!
- Ensure improper casing when loading static assets from
_static
does not result in false-positive file reads; thanks @andybee!
- Updated dependencies
- Fixed ability to configure
ARC_SESSION_TABLE_NAME
env var via.env
,pref[erence]s.arc
, etc.
- Added
@aws-sdk/node-http-helper
which is required by@architect/functions
when interacting with DynamoDB from a Node 18 process.node-http-helper
was likely available further down the dependency graph but has been removed at some point.
- Added additional
@http
HTTP API request datarequestContext
properties:http.protocol
+http.sourceIp
+http.userAgent
- Headers:
user-agent
+x-forwarded-for
+x-forwarded-port
+x-forwarded-proto
- Added additional
@http
REST API request datarequestContext
properties:protocol
+identity.sourceIp
+identity.userAgent
- Headers:
User-Agent
+X-Forwarded-For
+X-Forwarded-Port
+X-Forwarded-Proto
- Added additional
@ws
API request datarequestContext
properties:identity.sourceIp
$connect
headers:X-Forwarded-For
+X-Forwarded-Port
+X-Forwarded-Proto
- Added additional multi-tenant Lambda checks
- Updated dependencies
- Coerce type in
getRemainingTimeInMillis
Lambda context method
- Add
getRemainingTimeInMillis()
method to Node.js Lambda context; fixes #1427
- Updated dependencies
- Additional hardening to large request payloads via the runtime API
- Fixed issue where certain unicode data in very large Lambda response payloads may not parse correctly
- Added additional Lambda invocation and runtime API debug logging
- Fixed Lambda invocation issue when installed globally
- Fixed issue where very large uncompressed HTTP responses could become truncated
- Added support for compiled runtimes (Rust, Go, Java, etc.)
- Added support for Lambda runtime API (available during execution via
AWS_LAMBDA_RUNTIME_API
env var)
- Internal change: dramatically simplified Lambda execution lifecyle
- Unpinned
aws-sdk
from Lambda-specific version to enable SSO and resolve (unrelated) npm vulnerability warnings - Updated deps
- Updated deps
- Update deps, fix minor Glob v9 path issue
- Ensure SSM parameter names generated by
set.services
plugins agree with deployment; thanks @lpsinger!
- Improve printing env var and live AWS resource configuration
- Improve readme docs relating to which interfaces Sandbox binds to; thanks @lpsinger!
- Updated dependencies
- Allow ctrl+d keypress to quit Sandbox
- Fixed issue where Sandbox watcher would lose a specified port setting; fixes #1395
- Fixed issue where caller to Arc's CLI interface would unnecessarily execute a callback upon quitting
- Promotes livereload feature to being enabled by default
- Updated dependencies
- Updated dependencies
- Added support for
nodejs18.x
and AWS SDK v3 (@aws-sdk/*
) calls to Architect services
- Bump binary runtime to Node.js 18.x
- Fixed issue where Sandbox, running via Node.js 18.x, may fail to respond to local requests from the same host in Node.js <= 16.x
- Added Node.js 18.x to test matrix
- Updated dependencies
- Ensure CLI interface can be called with
quiet
option
- Updated dependencies
- Chill out Sandbox startup logging, moving more verbose status into
--verbose|-v
flag - Updated dependencies
- Updated dependencies
- Updated
pretty-print
to show which host Sandbox is listening on - Updated dependencies
- Fixed race condition where execution happening too fast may result in false
null
API Gateway responses - Fixed live reload when in use with
@architect/functions
brotli compression; fixes@architect/functions
#525 - Properly namespace
ARC_HOST
env var from host flag setting
- Added a host flag to specify the address to listen on.
- Updated dependencies;
lambda-runtimes
enablesnodejs16.x
- Updated dependencies
- Sandbox servers will now only listen to the loopback interface and will not listen for inbound connections from the network; thanks @lpsinger!
- Fail loudly when AWS-SDK finds a credentials file without default profile; thanks @stuartlangridge!
- Fixed Sandbox possibly hanging when it fails to start up in tests
- Updated dependencies
- Added support for seed data via
sandbox-seed.js[on]
(or custom) file
- Added
arc
property to plugin API calls, which should have been there - Froze
inventory
property in plugin API calls
- Fixed sandbox not detecting Lambda function return when process does not exit automatically; fixes #1319, thanks @mawdesley!
- Added SSM
ssm.getParameter()
support (in addition tossm.getParametersByPath()
) - Hardened Sandbox SSM emulation to have tighter query behavior, output valid errors, etc.
- Fixed Sandbox responding to all SSM requests indiscriminately
- Sandbox now only fulfills requests for the app that it's running (or for
@architect/functions
running as a bare module)
- Sandbox now only fulfills requests for the app that it's running (or for
- Enable
@architect/functions
to retrieve port configuration when run as a bare module and not within a Lambda - Run startup commands via
@sandbox-start
preferences pragma- This is a bit closer to
plugins.sandbox.start
than the existing@sandbox-startup
preferences pragma
- This is a bit closer to
- Fix missing
ARC_SANDBOX
env varversion
property insandbox.start
plugins +@sandbox-startup
scripts
- Fixed live reload behavior in Firefox where Firefox would reload the wrong path, preventing links from being accessed
- Architect 10 plugin API support! Specifically:
- Added Sandbox watcher API
- Added custom runtime support
- Added env setter plugin support
- Added live reload support!
- Add
@sandbox livereload true
to your preferences to enable - Your browser will automatically refresh any time a
get
orany
HTTP handler changes, or when any file insrc/shared
,src/views
, orpublic
changes
- Add
- Added ability to disable Sandbox watcher with
watcher
(boolean) in API option - Added port configuration via
prefs.arc
- The precedence order is now
prefs.arc
>port
API option or--port
CLI flag > environment variables - Also added
ARC_HTTP_PORT
env var for configuring the HTTP port (in addition toPORT
)
- The precedence order is now
- Added automatic port selection for internal service port configuration
- (Probably) never again will your multiple simultaneous Sandbox instances conflict with each other!
- HTTP port selection still defaults to
3333
and will halt Sandbox from starting if it conflicts (since it's presumably what you're expecting to see in your browser) - Any manually specified port conflicts will also halt Sandbox from starting
- Added Architect + userland env vars to startup scripts
- Breaking change: Architect no longer relies on or makes use of the
NODE_ENV
orARC_CLOUDFORMATION
env vars- Older versions of Node.js Architect libraries such as
@architect/functions
made use of these env vars, so it is wise to upgrade them at this time - Also be sure to consult the Architect upgrade guide
- Older versions of Node.js Architect libraries such as
- Breaking change: passing env vars in with the module's
env
option no longer merges those env vars with any found in.env
orprefs.arc
- The new env var precedence is
env
option >.env
>prefs.arc
- The new env var precedence is
- Breaking change: removed support for legacy
.arc-env
env files- Architect deprecated writing to
.arc-env
in late 2020; Sandbox will no longer read and use it for local environment variables - If you are still using a
.arc-env
file, please considerprefs.arc
or.env
for your local env vars
- Architect deprecated writing to
- Breaking change: removed
ARC_SANDBOX_ENABLE_CORS
env var option- Architect has supported
options
requests since version 8; that is the preferred approach to handling CORS
- Architect has supported
- Breaking change: bare CLI arguments related to logging (e.g.
sandbox quiet
) as aliases to flags are now discarded, please use CLI flags (e.g.sandbox --quiet
, orsandbox --debug
) - Breaking change: deprecate
ARC_SANDBOX_PATH_TO_STATIC
in favor ofARC_STATIC_BUCKET
for use with@architect/asap
- Internal change: switched to
chokidar
fromnode-watch
for file watching - Internal change: made Inventory responsible for handling
.env
env vars - Internal change: made Inventory responsible for figuring out
nodejs14.x
handler module systems and file names - Internal change: stopped populating default
arc-sessions
+data
tables; this was a quirky holdover behavior from early Architect that differed Sandbox from live AWS behavior - Prefer
ARC_SESSION_TABLE_NAME
toSESSION_TABLE_NAME
env var for Architect's built-in sessions management- All non-namespaced names will continue to be supported until at least Architect 11; we suggest changing them over to the namespaced equivalents as soon as is convenient
- Watcher now restarts Sandbox on preference file changes to ensure port changes and env vars are repopulated
- Fixed bug where multi-tenant Lambdas would error on startup
- Added support for Node.js 14 ESM in Lambda!
- Properly invoke Ruby with required keyword params; partial fix for #1291
- Added
lambdaSrc
propery (mapped fromlambda.src
) toARC_SANDBOX
context env var
- Updated dependencies
- Fixed HTTP route sorting; however you've organized your
@http
pragma, Sandbox should now behave much more like API Gateway; fixes #977
- Added support for
@tables-indexes
(which will eventually supersede@indexes
)- For more see: https://arc.codes/tables-indexes
- Updated dependencies
- Added internal
ARC_SANDBOX
env var for Sandbox metadata in Lambda invocations
- Fixed upcasing all userland environment variables
- Removed extraneous internal
__ARC*
environment variables from Lambda invocation
- Sandbox now immediately streams Lambda logs to the console instead of printing everything all at once upon completion of execution; thanks @andybee!
- Added runtime mismatch warnings
- Example: Sandbox will warn if your
get /foo
Lambda is configured for Python 3.9 and your local machine uses Python 3.8
- Example: Sandbox will warn if your
- Added
runStartupCommands
setting to API options- Defaults to
true
; settingfalse
disablesprefs.arc @sandbox-startup
commands, which may be useful for local testing; thanks @reconbot!
- Defaults to
- Added
env
option to API allowing programmatic control (add, replace, delete) of Lambda environment variables during automated testing, thanks @actsone8! - Added internal Arc service mock for API Gateway Management API mock for managing WebSocket connections via
aws-sdk
calls; big thanks to @reconbot!
- Sandbox will only ever print a given dependency issue one time, instead of upon each invocation
- Removed support for bare
port
CLI flag (e.g.arc sandbox port 12345
); Sandbox now requires either-p
or--port
for setting the port from the CLI
- Added warnings for macOS Monterey port conflicts on 5000 and 7000
- Updated dependencies
- Added Lambda context object with the following properties:
awsRequestId
(Node.js),aws_request_id
(Python / Ruby) - random GUID string, does not emulate AWS UUID4 request IDsfunctionName
(Node.js),function_name
(Python / Ruby) - identifiable function name string prefixed bysandbox-
; does not use live production AWS CFN GUIDsfunctionVersion
(Node.js),function_version
(Python / Ruby) - will always be$LATEST
invokedFunctionArn
(Node.js),invoked_function_arn
(Python / Ruby) - alwayssandbox
memoryLimitInMB
(Node.js),memory_limit_in_mb
(Python / Ruby) - your Lambda's configured memory amount
- Restored
ARC_INTERNAL
env var in Lambda invocations for Arc Functions - Restored userland env vars to
@sandbox-startup
scripts; thanks @reconbot! - Fixed case where
@ws
with no@http
or@static
would fail to start up
- Restored missing ARC_SANDBOX_PATH_TO_STATIC in Lambda env vars for manual ASAP use; fixes #1231, thanks @andybee!
- Sandbox now accepts a
apigateway
option, in addition to@aws apigateway
andARC_API_TYPE
env var- As before, valid options include:
http
(default if not passed),httpv1
,rest
- As before, valid options include:
- Sandbox can now be shipped as a binary via
pkg
- Added a new GitHub Actions workflow to per-platform build binary versions and run integration tests
- Route list now shows automatic static asset delivery at the root as mounting the public folder
- Projects that don't define root handlers will now load static assets from the root much, much faster!
- Internal: refactor to remove use of environment variables for passing data or config to various internals services, most notably the Lambda execution environment; fixes #1222
- Lambda executions' env vars are now completely pure and clean, having no extraneous host system env vars
- Sandbox no longer mutates env vars (with the exception of
ARC_ENV
andNODE_ENV
if unset or altered by preferences, such as@sandbox useAWS
) - Clean up any non-essential reliance tests may have on env vars previously populated by Sandbox
- Refactor tests to also stop mutating env vars, and to better clean up after themselves
- Internal: refactor to more cleanly and consistently pass common parameters around through critical code paths
- Added better support for
ARC_ENV
(instead of relying on / usingNODE_ENV
), helpful for improving reliability when running alongside certain other libraries that mutateNODE_ENV
- Fixed local symlinking issue introduced in 4.0.2
- Internal: Updated Architect Parser to v5
- Updated dependencies
- Update dependencies; resolve breaking changes from
ws@8.0.0
- Improved invocation behavior for JS functions where non-async handlers returning a Promise should not fail, thanks @reconbot!
- Improved WebSocket behavior when responding with !
200
; messages now respond with an error message instead of failing silently, thanks @reconbot!
- Fixed CLI when parsing larger port numbers (e.g.
--port 33333
); fixes #1023, thanks @filmaj + LumaKernel! - Fixed inconsistent error reporting, thanks @reconbot!
- Disable filesystem watching of node_modules and .git by default; fixes #1213
- Fixed WebSocket disconnect firing when Sandbox shuts down, thanks @reconbot!
- Breaking change: removed support for Node.js 10.x (now EOL, and no longer available to create / update in AWS Lambda)
- Breaking change: removed support for Architect 5 (and lower)
- This change in reality should not impact anyone, as Architect 5 LTS releases haven't used modern versions of Sandbox for quite some time
- Breaking change: removed internal tables lookup at
/_asd
, deprecated in favor of Sandbox's proper internal service discovery - Removed deprecated
@sandbox startup
warning - Update and tidy up dependencies
- Added more detailed
context
for WebSocket (@ws
) requests, thanks @reconbot!
- Refactored and improved WebSocket tests, also thanks @reconbot!
- Populate Sandbox startup commands (
prefs.arc
@sandbox-startup
) withARC_INV
env var, providing access to the project's Inventory object
- Ensure Sandbox startup commands respect
cwd
- Attempted to fix Sandbox not terminating processes properly when running in Lambda due to Lambda not having *nix
ps
- Hardened process termination testing
- Added
cwd
API param, making it easier to run Sandbox against one or many mock project directories in tests - Added
@ws
route printing
- Stopped making unnecessary Inventory calls during Sandbox / services startup, Sandbox now starts 10-25% faster most of the time
- Purified tests, removing all
process.chdir
calls (except those essential for testing the actual inferred working directory) - Updated dependencies
- Fixed issue where CLI might take a long time to reload local routes (or not reload them at all) due to issues related to Node.js stalling while closing its http server
- Fixed issue that could cause
sandbox.http.end()
andsandbox.events.end()
to hang during tests - Ensure plugin
invokeFunction
has all necessary params, fixes #1162 - Fixed issue where plugin functions might not be hydrated by Sandbox
- Internal change: added internal Arc service, including first service endpoint: SSM mock for proper internal service discovery to
aws-sdk
calls
- Fixed
@static spa
setting; thanks @timmak!
- Added new CLI flags for improved logging
--quiet
(-q
,quiet
) - suppresses logging--verbose
(v
,verbose
) - additional Sandbox data related to your userland environment and invocations--debug
(d
,debug
) - debug Sandbox internals (handy for Sandbox development)
- Cleaned up the output when triggering
@events
and@queues
Lambdae
- Improved file watcher error logging and handling
- Undid change that unnecessarily added Inventory object to WS requests; fixes #1121, thanks @pgte!
- Fixed an issue where Sandbox wouldn't kill a running Lambda if its configured timeout had expired, fixes #1137, thanks @andybee!
- Sandbox will now print a warning to the console if any running Lambdas time out
- Sandbox now supports named
@indexes
(via thename
parameter), fixes #1122
- Sandbox now works with an app composed of nothing but WebSockets, fixes #1099
- Sandbox can now handle non-JSON a bit more gracefully without blowing up, fixes #1093; thanks @reconbot!
- Handle multiple cookies according the spec, fixes #1090; thanks @zaverden!
- Fixed unnecessary warning generated regarding using aws-sdk as a dependency in production; thanks @andybee!
- Support for beta
@plugins
sandboxstart
andend
service hooks- Enables plugin authors to hook into sandbox, providing a local development experience for consumers of their plugin
- Added
invokeLambda
(viarequire('@architect/sandbox/invokeLambda')
) plugin helper method- Enables plugin authors to invoke Lambdas that their plugin creates during sandbox execution
- Internal change: added internal service discovery endpoint
- Gracefully handle file watcher limit error; thanks @mawdesley!
- Gracefully error if malformed JSON is passed to the
@events
bus server.
- Added environment
PYTHONPATH
to local Lambda executions (if present), thanks @scoates!
- Fixed minor typo in inaccessible dependency warning; thanks @jeremyw!
- Added
@sandbox-startup
preferences support, fixes #1032; thanks @rbethel!
- Deprecated the wonky and sometimes broken
@sandbox startup
setting (in favor of the above@sandbox-startup
pragma) - Make passing options object to Sandbox service methods, uh, optional
- The startup icon is now a Unicode heart
- Updated dependencies
- Fixed false positive dependency warnings when Lambda treeshaking encounters a
shared
orviews
directory with its own package.json file and dependencies; thanks @exalted - Fixed optional log suppression on a couple startup prints; fixes #1045, thanks @mikemaccana!
- Update (and limit) out of bounds dependency warnings to take into account Hydrate autoinstall during deploy
- Partially style error views
- Internal change: move
src/helpers
tosrc/lib
- Fixed alternative handler file checks when using Deno; fixes #1022
- Fixed formatting in unknown
@http
userland error state - Fixed middleware handling
ARC_SANDBOX_ENABLE_CORS
; thanks @neilhoff! - Fixed serving bare
@static
(i.e. S3-only with no@http
) apps; fixes #1031, thanks @dam! - Fixed issue where
any /*
could clobber the ability to send@ws
messages locally; fixes #1039, thanks @mikemaccana!
- Added support for new
@shared
pragma with selective shared code, uh, sharing - Added support for custom shared + views file paths
- Added support for global preferences lookup (
~/.preferences.arc
+~/.prefs.arc
, etc.) - Added response payload size validation;
@http
Lambdas with >6MB responses will now fail gracefully; thanks @andybee!
- Updated dependencies
- Development instructions in the readme for those wanting to hack, test, and iterate on Sandbox locally
- Gracefully fail when Sandbox startup script does not supply sufficient arguments; partially fixes #1019, thanks @filmaj!
- Added support for custom file paths in all function types
- Added support for new local preferences (
preferences.arc
orprefs.arc
) file- Add Sandbox preferences with
@sandbox
@env
(generated by runningarc env
, or added manually) populates environment variablescreate false
disables the local filesystem creator
- Example:
- Add Sandbox preferences with
@sandbox
create false # disables automatic function creation
startup
echo 'Hi there!'
npm run test
node some/arbitrary/script.js
@env
testing
AN_ENV_VAR somethingUseful
- Added
.env
support; thanks @wesbos! - Added missing Lambda handler error, and made ever so slightly nicer the error message presentation
- Breaking change on the Sandbox startup init script beta: existing startup scripts have replaced by startup preferences (
@sandbox startup
, see above)scripts/sandbox-startup.[js|py|rb]
must now be executable and callable from a shell via startup preferences (e.g.node scripts/sandbox-startup.js
)
- Implemented Inventory (
@architect/inventory
) - Removed legacy (and I do mean legacy) auto-initialization of
arc-sessions
table from Arc <5- Still initializing
{appname}-{env}-arc-sesssions
tables, though
- Still initializing
- Added more (hopefully) helpful environment-related init logging:
- Which environment is being loaded
- Whether Sandbox found any env vars for the current environment
- Whether Sandbox is using any live AWS infra (via prefs or
ARC_LOCAL
)
- Sandbox no longer creates missing Lambda resources by default; to reenable that, add to your preferences file:
@create
autocreate true
- Fixed wonky order of env population message printing in Sandbox
- Fixed weird side effects that can sometimes occur when toggling between symlink enabled/disabled with
@aws shared false
in a function config
- Improved rehydration behavior in CLI when symlinking is enabled
- Removed unnecessary dependency accidentally added in 3.1.0
- Internal change: laid some groundwork in Lambda invoker for new customization coming via Inventory
- Fixed obscure false positive missing dependency warning when
src/shared
is symlinked, and something insrc/shared
requires a module that's assumed to be in the function, but not insrc/shared
. It's weird, I know, but it can happen! - Fixed another obscure false positive missing dependency warning when
src/shared
is symlinked, and something insrc/shared
requires a module that's only found insrc/shared
, but not in the function itself. Maybe slightly less weird, but it can def happen!
- Added support for symlinking shared code into functions (
src/shared
andsrc/views
), which vastly improves Sandbox performance- Large projects utilizing shared code will see a 10-50x performance improvement on startup, and changes to shared code are now instantly reflected across all local functions
- To drop back into file-copying mode, invoke sandbox with
--disable-symlinks
(or if using Sandbox via API, passsymlink: false
in your options object) - If you are using
@static fingerprint true
, you will see a symlinkedstatic.json
in yoursrc/shared
folder. Feel free to add it to your .gitignore; while it isn't hurting anything, it will be dealt with in a future release - Legacy Windows operating systems that don't support symlinking will continue to copy shared code upon startup like some kind of hethen
- Shout out to @joliss!
- 3x expansion of integration test coverage (572 to 1784 integration tests)
- Internal change: Refactored and better documented body parsing middleware predicates
- Sandbox now responds to requests to root with only
/:param
defined inHTTP
APIs, fixes #981 - Improved root handling + ASAP fallthrough behavior
- Fixed obscure false negative for adding Arc Static Asset Proxy when
@http
contains a route that looks likeget /:hey/there
- Fixed parsing of duplicate query string params in deprecated (Arc v5) mode
- Fixed shutdown errors when using an external local DB, thanks @herschel666!
- Fixed issue where default region may prevent connections to external local DB, thanks @exalted!
- Fixed issue where WebSocket send events may fail in
HTTP
mode, thanks @grncdr! - Fixed issue where paths with a param and catchall (e.g.
/:item/*
) had malformed request payloads, fixes #983
- Added support for
@http
catchall syntax (e.g.get /api/*
) - Added support for
@http
any
method syntax (e.g.any /path
) - Added support for
@http
head
+options
methods - Added experimental support for
@proxy
- Added basic
requestContext
toREST
API requests
- Breaking change: with the addition of
@http
any
and*
, defaultget /
greedy catchall is now deprecated- To restore that behavior, either move your
get /
route toany /*
, or just define a newany /*
route
- To restore that behavior, either move your
- Updated dependencies
- Merged in patch from
2.0.4
to fix projects with@ws
- Fixed issue where projects with
@ws
fail to start up, thanks @grncdr!
- Removed startup notice regarding Sandbox defaulting to
HTTP
API emulation mode
- Fixed regression when using a non-Sandbox DynamoDB instance via the
ARC_DB_EXTERNAL
env var, thanks @herschel666 & @m-butler!
- Updated dependencies
- Added support for API Gateway
HTTP
APIs (with v1.0 and v2.0 payload formats)- API type configuration:
- Valid settings:
http
(default),httpv2
(aliased tohttp
),httpv1
, andrest
http
+httpv2
uses the latest API Gateway payload format (v2.0)- If you'd like to use
HTTP
APIs with code authored for an existingREST
API project, manually specify the v1.0 payload format withhttpv1
- If you'd like to use
- Backwards compatibility for
REST
APIs is retained withrest
setting - More info: https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html
- Valid settings:
- Your API type can be specified in the Architect project manifest as
@aws apigateway {type}
, or with theARC_API_TYPE
env var - API Gateway
HTTP
APIs as the new default API type in Sandbox may be a breaking change for local workflows with existing projects- If so, per above, make sure you set to
REST
mode withARC_API_TYPE=rest
or add that configuration to your project manifest - Existing projects with API Gateway
REST
APIs will remain unchanged and will continue to deploy safely, even though Sandbox now defaults toHTTP
- If so, per above, make sure you set to
- API type configuration:
- Added unified service interface and nascent API for Sandbox modules
- Sandbox itself and its various service modules (
http
,events
, andtables
) now have a consistent API to improve using Sandbox in your test suites- All Sandbox module methods now accept an options object, and can either return a Promise (e.g. can be used in async/await), or accept an optional callback
- Additionally, all Sandbox module methods now properly set their own environment variables, hydrate any necessary dependencies, and handle any other necessary service startup routines
sandbox.start()
and.end()
start and end all Sandbox services:sandbox.start(options[, callback]) → [Promise]
sandbox.end([callback]) → [Promise]
http.start()
and.end()
starts and ends just the HTTP / WebSocket service:http.start(options[, callback]) → [Promise]
http.end([callback]) → [Promise]
events.start()
and.end()
starts and ends just the event bus service:events.start(options[, callback]) → [Promise]
events.end([callback]) → [Promise]
tables.start()
and.end()
starts and ends just the local DynamoDB service:tables.start(options[, callback]) → [Promise]
tables.end([callback]) → [Promise]
- ~3x expansion of test coverage:
- Integration test suite expanded by 3x (124 to 358 integration tests)
- Unit test suite expanded by 2.5x (432 to 1,090 unit tests)
- A number of seldom used and largely undocumented Sandbox module APIs have a number of breaking changes:
sandbox.start()
no longer returns a function to shut down, and should now be shut down directly withsandbox.end()
sandbox.db()
is nowsandbox.tables()
http.close()
is nowhttp.end()
events.start()
&tables.start()
no longer return server objects to be invoked with.close()
, and should now be shut down directly withevents.end()
andtables.end()
- Fixed issue where Lambda timeouts were only respected if >3 seconds; now >=1 second is valid
- Refactored Arc v6 response support for multiValueHeaders to better accommodate use cases where headers & multiValueHeaders are not in conflict with each other
- Un-break Lambda invocation if an object is present in
.arc-config
- Updated dependencies
- Updated dependencies
- Fixed Deno issues on Windows (and added Deno to CI + integration tests), /ht @petruki
- Updated dependencies
- Fixed
process.stdin.setRawMode is not a function
error that may occur in certain circumstances; thanks @kristoferjoseph!
- Added (exprimental) support for manual rehydration while running:
- Press
shift
+H
to rehydrate all shared files - Press
shift
+S
to rehydrate src/shared - Press
shift
+V
to rehydrate src/views - Fixes #902, ht @andybee!
- Press
- Improves compatibility with production REST API behavior for non-get requests to root; fixes #900 /ht @andybee
- Added experimental support for manually opting into AWS's Java-based local DynamoDB; thanks @m-butler!
- Updated dependencies
- Fixed unsetting
@tables encrypt
setting locally; fixes #785, thanks @filmaj! /ht @m-butler
- Added support for
@static spa true|false
- Updated dependencies
- Response header casing now matches API Gateway (read: everything is lower-cased)
- Internal change: implemented new code standard with
@architect/eslint-config
- Fixed proxy lookup to custom 404 page
- Fixed incorrect filename in proxy 404 error message
- Response headers are now remapped (and in some cases dropped) per observed behavior in API Gateway
- Worth noting, this follows actually observed API Gateway behavior; what's published in their docs (link below) has been known to differ from reality
- https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-known-issues.html
- Fixes #879; /ht @andybee
- Fixed duplicate generation of table attribute definitions, fixes #828; thanks @filmaj, ht @exalted
- Sandbox support for Deno updated for
1.0.5
and entry now looks forindex.{js,ts,tsx}
andmod.{js,ts,tsx}
- Sandbox support for Deno updated for
1.0.3
; now forces reload every invocation
- Web socket
connectionId
was getting overwritten by concurrent client connections - Sending a message to a
connectionId
before it has connected should emit aGoneException
- h/t @andybee for helping track this down 🔍
- Adds Yarn support for hydration
- Improved default caching behavior for static assets; fixes #273
- Any assets that don't have
cache-control
explicitly set will now default to usingETag
in order to improve the reliability of cache invalidation - HTML & JSON responses still default to anti-caching headers
- Any assets that don't have
- Added path peeking (aka pretty URLs)
- Example: to load
/foo/index.html
, you used to have to request/foo/
- Example: to load
- Added ETag support to Sandbox static asset serving
- Fixed
ERR_FEATURE_UNAVAILABLE_ON_PLATFORM
error in Node.js 14; fixes #780, ht @stegosource
- Adds support for
multiValueHeaders
in response object; fixes #764, thanks @andybee!
- Fixed an issue where
multiValueHeaders
may conflict withheaders
values forContent-Type
; thanks @andybee! - Fixed an issue where errors weren't being handled if the database port conflicted on startup; thanks @exalted!
- Fixed
Deno.env()
becameDeno.env.toObject()
for the impending 1.x release
- Updated dependency status checker, fixes false positive rehyhdration of packages installed by archive or git repo
- Added Sandbox watcher pausing
- The presence of
_pause-architect-sandbox-watcher
in your operating system's$TMP
directory (usually/tmp
orc:\windows\temp
) will temporarily pause the Sandbox watcher - This is useful when combined with tools like
lint-staged
to ensure automated file stashing withinsrc/shared
andsrc/views
doesn't result in hydration failures - Sandbox cleans up this file on startup, jic
- The presence of
- Improved missing dependency warning to provide better instructions on how to install a missing dependency if the function in question does not already have a
package.json
file; /ht @exalted
- Fixed issue where explicit (or empty) returns would provide a red herring error
- When a non-existent
@events
Lambda is invoked, Sandbox will now gracefully fail
- Sandbox should now restore the terminal cursor more reliably when quit
- Preserve leading/trailing whitespace from console logging
- Fixed issue where
.arc-config
files with an@aws timeout
value of exactly900
(15 minutes) would not be respected
- Adds console logging for uncaught exceptions in async functions in Node.js and Deno; /ht @coco98
- Updated dependencies
- Sandbox should now restore the terminal cursor more reliably when shut down
- Updated the call to start Sandbox in Architect 6 such that it will now actually initiate the filesystem watcher
- Adds warning for out of bounds dependency loads
- This helps to ensure that potential side effects of running Node.js locally – such as the
require
algorithm traversing the filesystem outside the boundaries of the function in question – are less likely to be discovered after deploying to live AWS infra
- This helps to ensure that potential side effects of running Node.js locally – such as the
- Lambda's payload size limits are now respected and mocked; payloads exceeding 6MB will fail to execute, as they would in AWS
- Updated dependencies
- Fixes issue where HTTP requests with large body payloads error with E2BIG; fixes #639, /ht @dawnerd
- Minor improvements to auto-generated boilerplate function files
- Updated dependencies
.arc-env
env vars now support a wider variety of special characters (such as+
,@
,#
, etc.) if quoted, e.g.FOO "sp#ci@lch+rs"
; fixes #638- Fixed Architect project manifest syntax errors and error reporting
- Added support for running without an existing Architect project manifest
- Updated dependencies
- Query string arrays like
?ids=1&ids=2&ids=3&ids=4
are now consistent with API Gateway's requestmultiValueQueryStringParameters
property- Previously, the array-like value was available as an object in
request.queryStringParameters
(andrequest.query
in Arc 5 mode) which was inconsistent with API Gateway
- Previously, the array-like value was available as an object in
- Updated dependencies
- Added mocking of AWS's
multiValueHeaders
intoreq
- Also added mocking of the headers AWS drops from requests
- Fixes differences between AWS's inconsistent header casing and our existing lowcase-normalized header casing; fixes #698
- Sandbox now ensures
NODE_ENV
is one oftesting
,staging
, orproduction
(defaulting totesting
)
- Fixed issue where pulling changes down with git (or Mercurial) would not trigger filesystem changes; fixes #673
- Improves reliability of using Sandbox with certain test harnesses that may automatically set
NODE_ENV
- Added support for running multiple Sandboxes at the same time; fixes #635
- No more conflicting events and ports when running multiple simultaneous local Architect projects
- Also, you can now manually configure your
@events
port withARC_EVENTS_PORT
, and@tables
port withARC_TABLES_PORT
- Note: while unlikely, if you already manually specify your Sandbox's port, this may be a breaking change to your local workflow in two circumstances:
-
- You use Architect Functions; to fix, upgrade to Functions
3.6
or later
- You use Architect Functions; to fix, upgrade to Functions
-
- You hardcode an
@events
client to port3334
or DynamoDB client to port5000
; you should now read the ports fromARC_EVENTS_PORT
andARC_TABLES_PORT
- You hardcode an
- This change is NOT breaking to any live AWS / production infra
-
- Fixed AWS credential instantiation to ensure that missing
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
env vars are backfilled with dummy values in scenarios where valid credentials are not required
- Better support for quiet mode:
- Via params:
sandbox.start({quiet: true})
- Via env vars:
ARC_QUIET
(or legacyQUIET
) - Fixes #621; thanks @konsumer!
- Via params:
- Adds discrete
sandbox.end([callback])
method for shutting down the Sandbox in test environments- This method takes an optional callback or returns a promise
- Sandbox now sets the
ARC_CLOUDFORMATION
env var used by Architect Functions and other libs- This only occurs when running Sandbox against live infra (specifically:
NODE_ENV
=staging
||production
),
- This only occurs when running Sandbox against live infra (specifically:
- When called as module,
sandbox.end
now calls an optional callback or returns a promise; fixes #622, thanks @konsumer! - Sandbox now only starts the
@events
+@queues
bus and@tables
DB when called for by the Architect project manifest
- Improved logging for WebSocket invocations to be less confusing about potential non-error states when message action not found; fixes @sandbox#228
- Fixed potential destructuring bug in
sandbox.start
- Fixed secondary index (
@indexes
) naming schema issue introduced with Architect 6; fixed #45, thanks @eshikerya & @konsumer
- Updated dependencies
- Fixed local WebSocket port in
ARC_WSS_URL
- Added
ARC_WSS_URL
env var on startup (matches the environment variable behavior of Architect 6.0.25); fixed #225
- Updated default Lambda runtime to
nodejs12.x
(formerlynodejs10.x
) - Updated dependencies
- Fixed regression related to missing
aws-sdk
dependency errors
- Added
verbose
CLI flag (-v, --verbose, verbose
) and verbose-only dummy credentials warning
- Update dependencies
- Fixed errors related to missing
aws-sdk
dependency
- Sandbox now supports Deno runtime projects!
- Sandbox now passes full request params from WebSocket clients on
connect
anddisconnect
- Now in addition to
request.requestContext.connectionId
, you'll haverequest.headers
, andrequest.queryStringParameters
(if present) - Sandbox now only passes
request.body
to WebSocket functions that receivemessage
s (instead of adding an emptybody
object to all requests)
- Now in addition to
- Adds better backwards compatibility support for legacy
src/ws/ws-*
WebSocket function paths
- Added proper emulation of API Gateway v2's WebSocket connection authorization
- Returning an object containing
statusCode
2xx allows a WebSocket client to connect - Returning any other status code will hang up on the request
- Returning an object containing
- Added support for
nodejs12.x
andpython3.8
runtimes
- Updated dependencies
- Fixed printing of unnecessary ANSI escape characters in CI environments (
CI
env, or not TTY output)
- Fixed issue where
public/
may be automatically generated if@static folder
is defined
- Root requests now look for default
index.html
whenARC_STATIC_SPA=false
- Adds anti-caching and body parsing
application/vnd.api+json
; resolves #141, thanks @jkarsrud!
request.parameters
andrequest.pathParameters
are now properly passed through for root proxy requests
- Updated dependencies
- Updated dependencies
- Removed unnecessary dependency
- Internal change: swaps out
utils/init
for@architect/create
- Fixes issue when
@tables
definition includesstream true
; resolves #47, thanks @gr2m!
- Added update notifier to help ensure folks are running the (hopefully) least buggy, most stable, most secure version of Sandbox
- Updated dependencies
- Improves error states for missing static configs, 404s, etc. when using
@http
and/or@static
witharc.http.proxy
or without definingget /
- Legacy WebSockets paths on the filesystem are now formally deprecated
- Your default three WebSockets paths should be:
src/ws/default
,src/ws/connect
,src/ws/disconnect
- If you're using legacy WebSockets paths (either
src/ws/ws-default
orsrc/ws/ws-$default
), simply removews-[$]
and you should be all set!
- Your default three WebSockets paths should be:
- Fixed issue when emitting to WebSockets with Arc Functions (
arc.ws.send
); resolves #48, thanks @andybee + @bvkimball! - Fixed issue where
sandbox
may not have correctly resolved some custom WebSocket actions - Fixed HTTP request with
body
and noContent-Type
header; resolves #102, thanks @andybee! - Fixed issue where killed subprocesses would not trigger timeouts; resolves #30, /ht @mikemaccana
- Fixed issue where functions with legacy runtimes may not have been fully hydrated
- Updated dependencies
- Added support for
@static fingerprint true
in root spa / proxy requests- Also includes support for build-free calls between your fingerprinted static assets
- Example: in
public/index.html
, use the following syntax to automatically replace the local / human-friendly filename reference to the deployed fingerprinted filename: ${arc.static('image.png')}
will be automatically replaced byimage-a1c3e5.png
- Or
${STATIC('image.png')}
(which is the same thing, but shoutier) - Note: although those look like JS template literal placeholders, they're intended to live inside non-executed, static files within
public/
(or@static folder foo
)
- Example: in
- Also includes support for build-free calls between your fingerprinted static assets
- Updated dependencies
- Fixes root spa / proxy requests when Architect and/or Sandbox are globally installed; resolves #92 /ht @grahamb
- Startup auto-hydration now hydrates
src/views
andsrc/shared
- Updated dependencies
- When auto-hydrating functions upon startup,
sandbox
no longer hydratessrc/views
andsrc/shared
with each function
- Auto-hydration received a bunch of nice upgrades:
- Auto-hydration now detects changes to the state of your installed Node dependencies, and rehydrates if necessary; for example:
- You're working on a project, and a teammate updates a dependency in
get /foo
from version1.0.0
to1.1.0
- Upon your next git pull,
sandbox
will detect the dependency update inget /foo
and automatically install version1.1.0
for you
- You're working on a project, and a teammate updates a dependency in
- Auto-hydration now has a rate limit of one change every 500ms to prevent recursive or aggressive file updates
- Auto-hydration now has
@static folder
support - Auto-hydration now only hydrates the shared files necessary
- For example: if you change a file in
src/views
, it will only update your@views
functions, and not attempt to rehydrate all your project's functions withsrc/shared
- For example: if you change a file in
- Events now have a timestamp and improved formatting
- Auto-hydration now detects changes to the state of your installed Node dependencies, and rehydrates if necessary; for example:
- Beta:
sandbox
init script support!sandbox
will now run the init script of your choosing upon startup after all subsystems have started up:scripts/sandbox-startup.js
- a CommonJS module, receives your parsed Arc project as a parameter, supports async/awaitscripts/sandbox-startup.py
- a Python scriptscripts/sandbox-startup.rb
- a Ruby script
- Improvements to auto-hydration of
src/shared
andsrc/views
upon startup - Improvements to the conditions under which the HTTP server starts, shuts down, and restarts; fixes #65
- Improved async error copy (displayed when execution does not complete)
- Proxied requests now sends a proper
req.resource
, which can resolve some SPA bugs, esp when used with newer Arc Functions sandbox
now respects and errors on invalid response params for proper Architect 6 compatibility; fixes #49- Updates Dynalite to
3.0.0
, thanks @mhart! - Better 404 / file missing handling in
sandbox
when usinghttp.proxy
(or loading assets without@http get /
specified)
- Fixed issue where in certain circumstances
get /
wouldn't reload after a change to the project manifest - Minor fix where if you specified a
SESSION_TABLE_NAME
env var outside of.arc-env
,sandbox
won't clobber it - Fixed caching headers for various error states (async, timeout, etc.) to ensure your browser won't accidentally cache an error response
- Internal change: moves vendored HTTP proxy bundle into node module
- This change incorporates a number of fixes by way of
@architect/functions
(see below)
- Fixes issue where binary assets delivered via
sandbox
/ root may not be properly encoded - Fixes issue where
http.proxy.public
+http.proxy.read
may not have delivered correctly formatted responses in an Architect 5 environment
- Fixes callback error when auto-rehydrating
src/shared
andsrc/views
- Fixes empty mock
context
object encoding
- HTTP posts with empty bodies will no longer hang on request
sandbox.close
will no longer throw an error if project doesn't use@http
or@ws
- Patches vendored proxy bundle to 3.3.7
- Updated deps
- Tweaks Ruby execution to more closely align with cloud vendor behavior
- Fixes automatic dependency hydration during startup
Notes coming shortly!
- Support for Architect 6
- Includes complete compatibility for Architect 4 + 5 users
- Adds new built-in body parser for Arc 6 emulation
- Responses now include the same content type aware
Cache-Control
defaults as found in Architect 5- As always, they're able to be overriden with
cacheControl
param in Functions, orheaders['Cache-Control']
- As always, they're able to be overriden with
- Better emulation of proper AWS behavior when delivering binary responses
- Hopefully nothing breaking – please send feedback on the RC!
- Fixes dependency-free responses with
content-type
header set /ht @herschel666
- Resolves issue where static assets aren't loading from
_static/
, fixes #416
- Enables easier creation of static web apps by allowing
sandbox
to run only with@static
- In Architect 6, you will not need to specify or use
@http
routes in order to deliver web apps
- In Architect 6, you will not need to specify or use
- Fixed issue preventing Ruby functions from properly executing
- Fixed issue prevent Python functions from properly executing in Windows
- Fix broken characters in Windows console
- Context now passes an empty object (to be mocked soon!) to all runtimes
- This deprecates the legacy AWS implementation of
context
(since retired in production) passed tosandbox
Node functions
- This deprecates the legacy AWS implementation of
- Reorganized tests, added code coverage reports
- Adds auto-hydration to new functions without restarting
sandbox
- Fixes issue with auto-hydration on
sandbox
startup
- Expanded support for static asset fingerprinting! If you've enabled fingerprinting (
@static fingerprint true
):sandbox
will regenerate yourpublic/static.json
file on startup- And whenever making any changes to your
public/
dir,sandbox
auto-refresh will automatically regeneratepublic/static.json
and re-hydrate your shared files with the latest version
- Auto-refresh now detects file deletions from
src/shared
andsrc/views
- Expanded tests, code coverage, and Appveyor testing for Windows
- Fixes crashing when
get /
and other functions aren't defined in.arc
or present in the filesystem, but are requested by a client - Prevents startup of http server if
@http
isn't defined in.arc
- Adds PYTHONPATH to
sandbox
Lambda invocation for/vendor
modules
- Fix sandbox working on Windows by normalizing seperators to Unix
- Support naked WebSocket paths
- Auto-refresh!
sandbox
now keeps an eye out for the following changes to your project:- Edits to your Architect project manifest will mount or unmount HTTP routes without having to restart
sandbox
- Changes to
src/shared
andsrc/views
will automatically rehydrate your functions' shared code - More to come!
- Edits to your Architect project manifest will mount or unmount HTTP routes without having to restart
- Prettied up initialization printing
- Improved CLI tests
- Auto-hydration!
- Say goodbye to running
npx hydrate
before starting new projects, cloning existing projects, or pulling down new functions - On startup, any functions missing dependencies on the local filesystem will now be auto-hydrated
- Say goodbye to running
- Additional testing for
sandbox
CLI, and of sync and async calls as a module
- Ensures
sandbox
starts when local db initializes in the cases of:- No local AWS credentials file (e.g
~/.aws/credentials
) - The local AWS credentials file is present, but is missing the requested profile name
- Fixes #382, 391
- No local AWS credentials file (e.g
- Moves
sandbox
port assignment logic into this module (as opposed to various caller implementations)
- Print earlier, faster, more helpful startup messages
- Fixed gnarly little bug with missing Arc-supported runtimes
- Updates
utils
, moves some project config bootstrapping out ofsandbox
intoutils
- Better handling of missing project manifest
- Enables sandbox to run independently via CLI (
npx sandbox
)
- Uses shared banner printer
- Tidies up test suite and adds a few new tests
- Updates dependencies
- Corrects URI encoding when accessing local static assets in
_static/
, fixes #390
- This here library! Broken out of
@architect/architect
, we will now be maintainingsandbox
as a standalone module, and reincorporating it back into future versions of Architect.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.