feat: Extract git remote into its own option.

This makes the usage of git remotes more explicit and easier to
understand. It also allows to combine gitRemote and manifestPath
if the manifest file is not in the root of the git repository.

Author: calavera

API.md

@@ -54,23 +54,6 @@ lambda-project
     └── main.rs
 ```
 
-Note that `manifestPath` can be a remote git repository which will be cloned for you, i.e:
-
-```ts
-import { RustFunction } from 'cargo-lambda-cdk';
-
-new RustFunction(stack, 'Rust function', {
-  // Specify the branch to clone, defaults to HEAD.
-  branch: 'branch',
-  manifestPath: 'https://github.com/your_user/your_repo',
-  // Other flavors of git urls should work ☝️ too:
-  //
-  // https://github.com/user/repo.git
-  // ssh://user@host:22/user/repo.git
-  // [email protected]:user/repo.git
-});
-```
-
 ### Runtime
 
 The `RustFunction` uses the `provided.al2023` runtime. If you want to change it, you can use the property `runtime`. The only other valid option is `provided.al2`:
@@ -102,6 +85,28 @@ new RustFunction(this, 'Rust function', {
   ],
 });
 ```
+
+## Remote Git sources
+
+Both `RustFunction` and `RustExtension` support cloning a git repository to get the source code for the function or extension.
+To download the source code from a remote git repository, specify the `gitRemote`. This option can be a valid git remote url, such as `https://github.com/your_user/your_repo`, or a valid ssh url, such as `[email protected]:your_user/your_repo.git`.
+
+By default, the latest commit from the `HEAD` branch will be downloaded. To download a different git reference, specify the `gitReference` option. This can be a branch name, tag, or commit hash.
+
+If you want to always clone the repository even if it has already been cloned to the temporary directory, set the `gitForceClone` option to `true`.
+
+If you specify a `manifestPath`, it will be relative to the root of the git repository once it has been cloned.
+
+```ts
+import { RustFunction } from 'cargo-lambda-cdk';
+
+new RustFunction(stack, 'Rust function', {
+  gitRemote: 'https://github.com/your_user/your_repo',
+  gitReference: 'branch',
+  gitForceClone: true,
+});
+```
+
 ## Bundling
 
 Bundling is the process by which `cargo lambda` gets called to build, package, and deliver the Rust

README.md

@@ -2,8 +2,24 @@ import { mkdirSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join, parse } from 'node:path';
 import { tmpdir } from 'os';
 import { load } from 'js-toml';
+import { BundlingOptions } from './types';
 import { exec } from './util';
 
+/**
+ * Base properties for a Cargo project.
+ *
+ * RustFunctionProps and RustExtensionProps cannot inherit from this interface
+ * because jsii only supports direct inheritance from a single interface.
+ */
+interface CargoProject {
+  readonly bundling?: BundlingOptions;
+  readonly binaryName?: string;
+  readonly manifestPath?: string;
+  readonly gitRemote?: string;
+  readonly gitReference?: string;
+  readonly gitForceClone?: boolean;
+}
+
 export interface Workspace {
   members: string[];
 }
@@ -18,30 +34,40 @@ export interface Manifest {
   workspace?: Workspace;
 }
 
-export function getManifestPath(manifestPath: string, branch?: string, alwaysClone?: boolean): string {
+export function getManifestPath(project: CargoProject): string {
+  const defaultManifestPath = project.manifestPath || 'Cargo.toml';
+  let manifestPath = defaultManifestPath;
+
   // Determine what type of URL this is and download (git repo) locally
-  if (isValidGitUrl(manifestPath)) {
+  if (project.gitRemote && isValidGitUrl(project.gitRemote)) {
+    const gitReference = project.gitReference || 'HEAD';
+
     // i.e: 3ed81b4751e8f09bfa39fe743ee143df60304db5        HEAD
-    let latestCommit = exec('git', ['ls-remote', manifestPath, branch ?? 'HEAD']).stdout.toString().split(/(\s+)/)[0];
+    let latestCommit = exec('git', ['ls-remote', project.gitRemote, gitReference]).stdout.toString().split(/(\s+)/)[0];
     const localPath = join(tmpdir(), latestCommit);
 
-    if (alwaysClone) {
+    if (project.gitForceClone) {
       rmSync(localPath, { recursive: true, force: true });
     }
 
     if (!existsSync(localPath)) {
       mkdirSync(localPath, { recursive: true });
 
-      const args = ['clone', '--depth', '1', manifestPath, localPath];
-      if (branch !== undefined) {
-        args.push('--branch', branch);
+      const args = ['clone'];
+      if (gitReference === 'HEAD') {
+        args.push('--depth', '1');
       }
 
+      args.push(project.gitRemote, localPath);
       exec('git', args);
-    }
 
-    // Append Cargo.toml to the path
-    manifestPath = join(localPath, 'Cargo.toml');
+      if (gitReference !== 'HEAD') {
+        exec('git', ['checkout', gitReference], { cwd: localPath });
+      }
+
+      // Append Cargo.toml to the path
+      manifestPath = join(localPath, defaultManifestPath);
+    }
   }
 
   let manifestPathResult;

package.json

@@ -2,10 +2,20 @@ import { LayerVersion, LayerVersionOptions } from 'aws-cdk-lib/aws-lambda';
 import { Construct } from 'constructs';
 import { Bundling } from './bundling';
 import { getManifestPath } from './cargo';
+// import { CargoProject } from './cargo';
 import { BundlingOptions } from './types';
 
-
+/**
+ * Properties for a RustExtension
+ */
 export interface RustExtensionProps extends LayerVersionOptions {
+  /**
+ * Bundling options
+ *
+ * @default - use default bundling options
+ */
+  readonly bundling?: BundlingOptions;
+
   /**
    * The name of the binary to build, in case that's different than the package's name.
    */
@@ -14,47 +24,48 @@ export interface RustExtensionProps extends LayerVersionOptions {
   /**
    * Path to a directory containing your Cargo.toml file, or to your Cargo.toml directly.
    *
-   * This will accept a directory path containing a `Cargo.toml` file, a filepath to your
-   * `Cargo.toml` file (i.e. `path/to/Cargo.toml`), or a git repository URL
-   * (e.g. `https://github.com/your_user/your_repo`).
-   *
-   * When using a git repository URL, the repository will be cloned to a temporary directory.
+   * This will accept a directory path containing a `Cargo.toml` file (i.e. `path/to/package`), or a filepath to your
+   * `Cargo.toml` file (i.e. `path/to/Cargo.toml`). When the `gitRemote` option is provided,
+   * the `manifestPath` is relative to the root of the git repository.
    *
    * @default - check the current directory for a `Cargo.toml` file, and throws
    *  an error if the file doesn't exist.
    */
   readonly manifestPath?: string;
 
   /**
-   * Bundling options
+   * The git remote URL to clone (e.g `https://github.com/your_user/your_repo`).
    *
-   * @default - use default bundling options
+   * This repository will be cloned to a temporary directory using `git`.
+   * The `git` command must be available in the PATH.
    */
-  readonly bundling?: BundlingOptions;
+  readonly gitRemote?: string;
 
   /**
-   * The branch to clone if the `manifestPath` is a git repository.
+   * The git reference to checkout. This can be a branch, tag, or commit hash.
+   *
+   * If this option is not provided, `git clone` will run with the flag `--depth 1`.
    *
    * @default - the default branch, i.e. HEAD.
    */
-  readonly branch?: string;
+  readonly gitReference?: string;
 
   /**
-   * Always clone the repository if using a git `manifestPath`, even if it has already been
+   * Always clone the repository if using the `gitRemote` option, even if it has already been
    * cloned to the temporary directory.
    *
-   * @default - clones only if the repository and branch does not already exist in the
+   * @default - clones only if the repository and reference don't already exist in the
    * temporary directory.
    */
-  readonly alwaysClone?: boolean;
+  readonly gitForceClone?: boolean;
 }
 
 /**
  * A Lambda extension written in Rust
  */
 export class RustExtension extends LayerVersion {
   constructor(scope: Construct, resourceName: string, props?: RustExtensionProps) {
-    const manifestPath = getManifestPath(props?.manifestPath ?? 'Cargo.toml', props?.branch, props?.alwaysClone);
+    const manifestPath = getManifestPath(props || {});
     const bundling = props?.bundling ?? {};
 
     super(scope, resourceName, {

src/cargo.ts

@@ -11,61 +11,69 @@ export { cargoLambdaVersion } from './bundling';
  * Properties for a RustFunction
  */
 export interface RustFunctionProps extends FunctionOptions {
-  /**
-   * The name of the binary to build, in case that's different than the package's name.
-   */
-  readonly binaryName?: string;
-
   /**
    * The Lambda runtime to deploy this function.
    * `provided.al2023` is the default runtime when this option is not provided.
    */
   readonly runtime?: 'provided.al2023' | 'provided.al2';
 
+  /**
+  * Bundling options
+ *
+ * @default - use default bundling options
+ */
+  readonly bundling?: BundlingOptions;
+
+  /**
+   * The name of the binary to build, in case that's different than the package's name.
+   */
+  readonly binaryName?: string;
+
   /**
    * Path to a directory containing your Cargo.toml file, or to your Cargo.toml directly.
    *
-   * This will accept a directory path containing a `Cargo.toml` file, a filepath to your
-   * `Cargo.toml` file (i.e. `path/to/Cargo.toml`), or a git repository url
-   * (e.g. `https://github.com/your_user/your_repo`).
-   *
-   * When using a git repository URL, the repository will be cloned to a temporary directory.
+   * This will accept a directory path containing a `Cargo.toml` file (i.e. `path/to/package`), or a filepath to your
+   * `Cargo.toml` file (i.e. `path/to/Cargo.toml`). When the `gitRemote` option is provided,
+   * the `manifestPath` is relative to the root of the git repository.
    *
    * @default - check the current directory for a `Cargo.toml` file, and throws
    *  an error if the file doesn't exist.
    */
   readonly manifestPath?: string;
 
   /**
-   * Bundling options
+   * The git remote URL to clone (e.g `https://github.com/your_user/your_repo`).
    *
-   * @default - use default bundling options
+   * This repository will be cloned to a temporary directory using `git`.
+   * The `git` command must be available in the PATH.
    */
-  readonly bundling?: BundlingOptions;
+  readonly gitRemote?: string;
 
   /**
-   * The branch to clone if the `manifestPath` is a git repository.
+   * The git reference to checkout. This can be a branch, tag, or commit hash.
+   *
+   * If this option is not provided, `git clone` will run with the flag `--depth 1`.
    *
    * @default - the default branch, i.e. HEAD.
    */
-  readonly branch?: string;
+  readonly gitReference?: string;
 
   /**
-   * Always clone the repository if using a git `manifestPath`, even if it has already been
+   * Always clone the repository if using the `gitRemote` option, even if it has already been
    * cloned to the temporary directory.
    *
-   * @default - clones only if the repository and branch does not already exist in the
+   * @default - clones only if the repository and reference don't already exist in the
    * temporary directory.
    */
-  readonly alwaysClone?: boolean;
+  readonly gitForceClone?: boolean;
 }
 
 /**
  * A Rust Lambda function
  */
 export class RustFunction extends Function {
   constructor(scope: Construct, resourceName: string, props?: RustFunctionProps) {
-    const manifestPath = getManifestPath(props?.manifestPath ?? 'Cargo.toml', props?.branch, props?.alwaysClone);
+    const manifestPath = getManifestPath(props || {});
 
     const runtime = new Runtime(props?.runtime || 'provided.al2023');
     const bundling = bundlingOptionsFromRustFunctionProps(props);

src/extension.ts

@@ -54,7 +54,7 @@ describe('bundlingOptionsFromRustFunctionProps', () => {
 const forcedDockerBundling = !!env.FORCE_DOCKER_RUN || !cargoLambdaVersion();
 
 const getTestManifestPath = () => {
-  return getManifestPath(path.join(__dirname, 'fixtures/single-package/Cargo.toml'));
+  return getManifestPath({ manifestPath: path.join(__dirname, 'fixtures/single-package/Cargo.toml') });
 };
 
 const templateWithProps = (props?: RustFunctionProps) => {

src/function.ts

@@ -4,22 +4,22 @@ import { getManifest, getManifestPath } from '../src/cargo';
 describe('getManifestPath', () => {
   it('works with a path to an existent Cargo.toml file', () => {
     const fixture = join(__dirname, 'fixtures/single-package/Cargo.toml');
-    expect(getManifestPath(fixture)).toEqual(fixture);
+    expect(getManifestPath({ manifestPath: fixture })).toEqual(fixture);
   });
 
   it('works with a base directory', () => {
     const fixture = join(__dirname, 'fixtures/single-package');
-    expect(getManifestPath(fixture)).toEqual(join(fixture, 'Cargo.toml'));
+    expect(getManifestPath({ manifestPath: fixture })).toEqual(join(fixture, 'Cargo.toml'));
   });
 
   it('fails with a different file', () => {
     const fixture = join(__dirname, 'fixtures/single-package/src/main.rs');
-    expect(() => getManifestPath(fixture)).toThrow('manifestPath is specifying a file that is not Cargo.toml');
+    expect(() => getManifestPath({ manifestPath: fixture })).toThrow('manifestPath is specifying a file that is not Cargo.toml');
   });
 
   it('fails with a directory that doesn\'t include a Cargo.toml file', () => {
     const fixture = join(__dirname, 'fixtures/single-package/src');
-    expect(() => getManifestPath(fixture)).toThrow(`'${fixture}/Cargo.toml' is not a path to a Cargo.toml file, use the option \`manifestPath\` to specify the location of the Cargo.toml file`);
+    expect(() => getManifestPath({ manifestPath: fixture })).toThrow(`'${fixture}/Cargo.toml' is not a path to a Cargo.toml file, use the option \`manifestPath\` to specify the location of the Cargo.toml file`);
   });
 });