Skip to content
This repository has been archived by the owner on May 18, 2021. It is now read-only.

v2.0.0 design doc

Jump to bottom
Nick Irvine edited this page Jan 7, 2020 · 3 revisions

We tried doing a refactor, but it's just too hard given the spaghetti-code nature of the existing code base.

The library is separate from the CLI

Some users have expressed interest in calling aws-okta from code. This requires a decent and stable API.

This would also improve code quality and testability.

The library and the CLI must be separate Go modules.

The library is:

  • is unit-testable
  • is minimal
  • has a stable, public API

The CLI is:

  • has prompters and other UI components
  • has config file loader
  • has keyring-based session cache(s)
  • is harder to unit test
  • has a

Rollout

v2 of the CLI might break some behaviours (especially undocumented ones), but should be mostly compatible. v2 of the lib however will not be API compatible at all, and no effort to make a migration guide or anything will be made.

No v1 release of the CLI or the lib exist. We basically have v1 in everything but name currently, so we might as well call it that. v1 does not include a CLI/lib separation, and will immediately enter maintenance mode: bugfixes only.

CLI v2 we should dog-food significantly at Segment before cutting v2.0.0.

The branch staging/v2.0.0 is treated as the mainline branch for v2.0.0 until v2.0.0 is cut, at which point master will be branched to mainline/v1.0.x, which will be mainline for v1.0.x.

Release candidate milestones

v2.0.0-rc1: add and exec with Duo 2FA

The main flow at Segment.

  • phone1 Duo factor only
  • AssumeRoleWithSAML to Okta only (no source_profile)

New Style Guide

lib errors should probably be types, and these shall be named Err*

Sometimes a sentinel value is fine, if there's nothing inspectable about the error:

var ErrBadThing = errors.New("a bad thing happened")

Consider not exporting this type if you don't expect the consumer to inspect or handle it.

As soon as you reach for fmt.Errorf("%s"), you should probably make this a full-blown type.

unhandled lib errors should probably be wrapped

...using fmt.Errorf("...: %w", err)

cli cobra commands can return fmt.Errorf("whatever")

Since these errors just get displayed to the user and aren't types.

Makefiles are bad and we should avoid using them

We don't need the main benefit of Makefiles (cached build objects) because Go does that for us. Everything else can be done with bash, a reasonable (but admittedly crusty), imperative programming language. Bash is hard enough without also requiring the DAG-based language of make.

Clone this wiki locally