Skip to content

Latest commit

 

History

History
63 lines (51 loc) · 5.48 KB

DEVELOPER_NOTES.md

File metadata and controls

63 lines (51 loc) · 5.48 KB
Raw

Developer Notes

Walkthrough

  • Project implementation is first broken up into two parts, cli and lib.
    • The cli—short for 'command line interface'—deals with taking input from the user, parsing commands, generating help, etc. Basically, all the user stuff.
    • The cli also handles validating user input.
    • The lib—short for library—creates a reusable library that can be incorporated into other projects.
  • Valid cli input is defined in the cliSpec (in src/cli/constants.mjs) object, which is used to parse input as well as generate API documentation and "help".
    • Command procesing is handled by a series of hierarchial handlers.
    • At the top level, cloudsite.mjs processes top level options (like '--quiet') and then passes control to a "handler" function for further processing.
    • Each handler function then processes command/command group specific options.
    • Control is then passed either to one of the Cloudsite action handlers (defined in lib), or when the command group 'configurations' is specified, passes control to a third layer cli handler for processing of the subcommand.
    • The 'configuration' subcommand handlers process the final subcommand options and then directly implement the commands. The thinking here being that 'configuration' is a concept in the cli itself whereas the lib actions deal exclusively with managing the site infrastructure and content.
  • For non-configuration commands, the cli command handler passes control to the lib component.
  • The lib components manage site infrastructure and content through seven commands:
    • cloudsite create,
    • cloudsite list,
    • cloudsite detail,
    • cloudsite verify,
    • cloudsite update
    • cloudsite destroy,
    • cloudsite import.
  • The 'create' action is used to create a new site:
    • generates an SSL certificate for the site,
    • uses CloudFormation to create an S3 bucket, security policies, and CloudFront distribution, and
    • copies the site contents to S3.
    • The action is safe to repeat, which is useful in the case of partial creation.
    • Basic site information is stored locally (in ~/.config/cloudsite/sites.json) for future reference. This reduces the need to make API calls to manage sites.
  • The 'list' action is used to list known sites.
  • The 'detail' action prints detailed information about the site configuration.
  • The 'verify' action checks that the infrastructure and content of a live site is up to date.
  • The 'update' action is used to update site infrastructure and/or content.
  • The 'destroy' action is used to destroy (delete/remove) all site resources.
  • The 'import' action examines existing AWS resources, identifies existing sites, and updates the local site database (in ~/.config/cloudsite/sites.json).

Dependencies organization

All the CLI dependencies are noted as peer dependencies. This is so that if the package is being installed as a library, you can run npm i --omit peer.

TODOs

Limitations and future goals

See also the Known limitations section in the README.md.

  • The current implementation deals exclusively with apex domains. It would make a lot of sense to support sub-domains as well.
  • We want to move to a more flexible and consistent output protocol. All actions should support 'quiet'-ing intermediate output and a single, formatable output object.[^1]

[^1: We did a survey of "top javascript log libraries" and determined that Winston seemed to fit best. It had all the feataures we needed and is very well supported.]

References and credits