github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/adr/0020-package-sources.md (about)

     1  # 20. Package Sources
     2  
     3  Date: 2023-09-28
     4  
     5  ## Status
     6  
     7  Accepted
     8  
     9  ## Context
    10  
    11  Jackal natively supports creating the following package sources:
    12  
    13  - Local Tarball (`.tar` and `.tar.zst`)
    14    - Via `jackal package create <dir> -o <dir>`, with compression determined by `metadata.uncompressed` in `jackal.yaml`
    15  - Split Tarball (`.part...`)
    16    - Via `jackal package create <dir> --max-package-size <size> -o <dir>`
    17  - OCI package (`oci://`)
    18    - Via `jackal package publish <source> oci://` or `jackal package create <dir> -o oci://...`
    19  - In-cluster (Deployed) package
    20    - Post `jackal package deploy <source>` the package is show in `jackal package list`
    21  
    22  However, the current loading abilities of Jackal have been inconsistent depending upon the action specified. For example:
    23  
    24  - Split tarball packages could be created, deployed, but not inspected, or removed
    25  - In-cluster packages could be removed (by name), but not inspected
    26  - HTTPs URLs could be deployed, but not inspected, or removed
    27  - etc...
    28  
    29  ## Decision
    30  
    31  Jackal must support the `deploy`, `inspect`, `remove`, `publish`, `pull`, and `mirror-resources` commands across package sources.
    32  
    33  For common behavior to be exhibited by all sources, the `PackageSource` interface has been introduced along with the `layout` library.
    34  
    35  ```go
    36  // src/pkg/packager/sources/new.go
    37  
    38  // PackageSource is an interface for package sources.
    39  //
    40  // While this interface defines three functions, LoadPackage, LoadPackageMetadata, and Collect; only one of them should be used within a packager function.
    41  //
    42  // These functions currently do not promise repeatability due to the side effect nature of loading a package.
    43  type PackageSource interface {
    44      // LoadPackage loads a package from a source.
    45      //
    46      // For the default sources included in Jackal, package integrity (checksums, signatures, etc.) is validated during this function
    47      // and expects the package structure to follow the default Jackal package structure.
    48      //
    49      // If your package does not follow the default Jackal package structure, you will need to implement your own source.
    50      LoadPackage(*layout.PackagePaths) error
    51      // LoadPackageMetadata loads a package's metadata from a source.
    52      //
    53      // This function follows the same principles as LoadPackage, with a few exceptions:
    54      //
    55      // - Package integrity validation will display a warning instead of returning an error if
    56      //   the package is signed but no public key is provided. This is to allow for the inspection and removal of packages
    57      //   that are signed but the user does not have the public key for.
    58      LoadPackageMetadata(dst *layout.PackagePaths, wantSBOM bool, skipValidation bool) error
    59  
    60      // Collect relocates a package from its source to a tarball in a given destination directory.
    61      Collect(destinationDirectory string) (tarball string, err error)
    62  }
    63  ```
    64  
    65  The following sources have been implemented:
    66  
    67  - Local Tarball (`.tar` and `.tar.zst`)
    68  - Split Tarball (`.part...`)
    69  - HTTP(S) URL
    70  - Published OCI package (`oci://`)
    71  - In-cluster (Deployed) package (`inspect` and `remove` only)
    72  
    73  The `layout` library contains the `PackagePaths` struct which supercedes the prior `TempPaths` struct. This new struct contains access methods to different aspects of Jackal's internal package layout. This struct is passed to the `PackageSource` functions to allow for the loading of packages into the correct layout. In order for a package to be loaded into the correct layout, the package must follow the default Jackal package structure, or be converted to the expected structure during loading operations.
    74  
    75  ## Consequences
    76  
    77  The `PackageSource` interface and `layout` library are now part of the public API of Jackal. This means that any package source can be implemented by a third party and used with Jackal as a first class citizen.
    78  
    79  By moving towards a behavioral driven design, Jackal is now more consistent in its behavior across all package sources. If it walks like a source, and it quacks like a source, it's a source.