Skip to content

Commit

Permalink
docs: add use cases for strict and fallback network modes
Browse files Browse the repository at this point in the history
  • Loading branch information
ngshiheng committed Jul 3, 2023
1 parent 187b989 commit e0a7805
Showing 1 changed file with 18 additions and 2 deletions.
20 changes: 18 additions & 2 deletions docs/content/configuration/network.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,30 @@ The NetworkMode configuration in Athens determines how results are returned by t

There are 3 modes available for the NetworkMode configuration. To configure the `NetworkMode` settings at `config.dev.toml`, set the `NetworkMode` to 1 of the 3 available modes:

1. `strict`: In this mode, Athens will merge versions from the VCS and storage, but will fail if either of them fails. This mode provides the most consistent results.
1. `strict`: In this mode, Athens will merge versions from the VCS and storage but will fail if either of them fails. This mode provides the most consistent results.

2. `offline`: This mode only retrieves versions from Athens' storage and never reaches out to the VCS.

3. `fallback`: This mode retrieves versions from Athens' storage only if the VCS fails. Note that using this mode may result in inconsistent results since fallback mode does its best to provide the available versions at the time of the request.

## Use cases

### Ensuring consistency in module version retrieval

When working in environments that prioritize consistency and reliability, configuring Athens with the `strict` mode guarantees a dependable and predictable module version resolution mechanism.

Using the `strict` mode, Athens merges module versions from its storage and the VCS, while ensuring that any failure in either source results in a failure response.

Choose Athens' `strict` network mode for a reliable and consistent approach to module version retrieval.

### Fetching modules for offline environments

When working in offline environments with private networks lacking direct internet access, Athens' offline mode can be useful. For example, you can [pre-download](/configuration/prefill-disk-cache/) modules using Athens from a machine with internet access. Subsequently, the pre-downloaded modules are accessible within the offline network through Athens, facilitating development and build without requiring an active internet connection.
When working in offline environments with private networks lacking direct internet access, Athens' `offline` mode can be useful.

For example, you can [pre-download](/configuration/prefill-disk-cache/) modules using Athens from a machine with internet access. Subsequently, the pre-downloaded modules are accessible within the offline network through Athens, facilitating development and builds without requiring an active internet connection.

### Ensuring availability of modules versions

In certain situations, the stability or availability of the VCS may vary. To mitigate potential disruptions, Athens offers the `fallback` mode. If the VCS encounters issues or fails to respond, Athens falls back to serving modules from its storage to ensure continued availability.

However, using the `fallback` mode may result in inconsistent results. Athens will provide the available versions at the time of the request, which may differ from the latest versions in the VCS.

0 comments on commit e0a7805

Please sign in to comment.