Skip to content

Architecture Guide

Jump to bottom
Al Berez edited this page May 15, 2024 · 28 revisions

CF CLI Architecture Diagram

All CF CLI major versions have their own branch (e.g. v6).

CLI Architecture

Glossary:

  • main.go (Orange): Entry point into the CF CLI.
  • Command Lists (Grey): List of CLI commands contained in that version of the CF CLI. This is dependent on the branch of the CLI. The v6 branch has a v6 command list. Branches after v6 (currently v7 and master) have a v7 command list. The names command_list_v6 and command_list_v7 are leftover from when the CLI built both the v6 and v7 CLI from the same branch. Going forward, they can just be thought of as just command_list.
  • Command Packages (Yellow): These packages manage the UX/UI logic for each individual command.
  • Actor Packages (Teal): These packages manage the business logic for the entire CLI. The V6 CLI actors are divided by Cloud Controller API version; the push and V2/V3 actors are required to mitigate the complexity of integrating the V2 and V3 API versions. The V7 CLI utilizes the V7 Actor package for V7 specific commands.
  • API Packages (Green): These packages manage the API requests made to the Cloud Controller/UAA/Networking/etc. These API requests do not contain any business logic; they are simple abstractions of individual API requests.
  • Plugin Packages/Legacy Code (Red): These packages manage the CLI Plugin interface as well as the Legacy CLI code. The plugin interface exclusively talks to the Legacy Code. The Legacy Code only interacts with the Cloud Controller V2 API, UAA API, and the Routing API.

General Command Flow

When a CLI command is executed, the following process occurs:

  1. All the command line arguments (i.e. os.Args) are provided to the go-flags package with the appropriate branch specific command list (e.g: v6).
  2. go-flags will use the command line arguments to instantiate the correct command struct and populate the struct's fields.
  3. The command's Setup function is called with a preloaded UI and an in memory copy of the CLI config. This Setup function creates all the necessary API clients and Actors required for the command.
  4. The command's Execute function is called; the Execute function [generally] runs through the following:
    1. Validates/sanitizes the user provided input.
    2. API version checks based on provided input.
    3. Verifies API targets based on command requirements.
    4. Outputs "flavor" text to indicate to the user that desired action is about to be processed.
    5. Calls appropriate Actor function(s) to perform command's action. (See step #5 for more information)
    6. Displays output of Actor function(s) depending on command's intent.
  5. When an Actor function is called, one or more API calls are made to the Cloud Controller, UAA, Networking API, and so on. Any complex logic regarding the response of these APIs are handled within the Actor function, returning the final result of said API calls or an error indicating why the Actor function could not proceed.
  6. When a command has returned from its Execute, any changes to the CLI config are written to disk.

V6 CLI Packages/Files

The v6 CLI uses the v6 CLI Command List. This command list points exclusively to the commands under command/v6, command/common, and command/plugin. Each command uses some combination of the v2action.Actor, v3action.Actor, v2v3action.Actor, and the Push.Actor to perform the desired action.

The following is a list of files exclusive to the V6 CLI:

└── command
    └── common
        ├── command_list_v6.go # Different Command list
        └── internal
            ├── help_all_display_v6.go # Different help list
            └── help_common_display_v6.go # Different help list

V7 Packages/Files

The V7 CLI's command list is identical to the V6 CLI's command list, with the exception of some command/v7 commands overwriting the analogous command/v6 commands. These command/v7 commands should exclusively use the actor/v7action package to perform their business operations.

Note: While the Cloud Controller V3 API is transitioning, there may be a need to temporarily use the v2action package to fill in missing functionality in the v7action package.

The following is a list of files exclusive to the V7 CLI:

├── actor
│   └── v7actor # V7 specific business logic
└── command
    ├── common
    │   ├── command_list_v7.go # Different Command list
    │   └── internal
    │       ├── help_all_display_v7.go # Different help list
    │       └── help_common_display_v7.go # Different help list
    └── v7 # Over written V7 versions of V6 commands

Refactored vs. Legacy Code

The CLI architecture described above is the Refactored code. The unrefactored Legacy Code lives in the cf directory and does not follow the layered Command/Actor/API paradigm. Legacy commands are in the process of being refactored into this new architecture.

To determine which CLI command triggers the Legacy Code, the command will raise an UnrefactoredCommandError which is caught by main.go; once main.go catches the error, the command line arguments are rerun/reprocessed entirely through the Legacy Code.

Clone this wiki locally