Merge branch 'main' of github.com:45Drives/houston-common into main

.github/workflows/publish-docs.yaml

@@ -34,9 +34,9 @@ jobs:
         yarn docs
     - id: "upload-documentation"
       name: "Upload Pages artifact"
-      uses: "actions/upload-pages-artifact@v2"
+      uses: "actions/upload-pages-artifact@v3"
       with:
         path: "docs/"
     - id: "deployment"
       name: "Deploy documentation to GitHub Pages"
-      uses: "actions/deploy-pages@v2"
+      uses: "actions/deploy-pages@v4"

README.md

@@ -1,2 +1,51 @@
 # houston-common
 Common library for Houston
+
+## API Documentation
+https://45drives.github.io/houston-common/
+
+## Result/ResultAsync documentation from neverthrow
+https://github.com/supermacro/neverthrow
+
+## Example
+### Running command and processing output
+```ts
+import { server, Command, unwrap } from "@45drives/houston-common-lib";
+
+function findFile(searchPath: string, filename: string): ResultAsync<string[], ProcessError> {
+  return server
+    .execute(new Command(["find", searchPath, "-name", filename, "-print0"]))
+    .map((proc) => proc.getStdout().split("\0"));
+}
+const findResult = findFile("/home/user", "id_rsa.pub"); // findResult could contain either list of file paths or a ProcessError
+
+// 1. use findResult through map method
+findResult.map((filePaths: string[]) => {
+  // this callback only runs if findResult was successful
+  doSomethingWith(filePaths);
+});
+
+// 2. or use findResult through match
+findResult.match(
+  (filePaths: string[]) => {
+    // this callback only runs if findResult was successful
+    doSomethingWith(filePaths);
+  },
+  (err: ProcessError) => {
+    // this callback only runs if findResult failed
+    handleError(err);
+  }
+);
+
+// 3. or if whatever you are doing to the result also returns a Result, use .andThen instead of .map
+const rmResult = findResult.andThen((filePaths: string[]) =>
+  // this callback only runs if findResult was successful
+  server.execute(new Command(["rm", ...filePaths]))
+);
+
+// 4. or if you'd rather not use Result and a) throw ProcessError if the command failed
+const foundPathsOrThrow: string[] = await unwrap(findResult);
+
+// 4. b) fallback to default value if failed, ignoring error:
+const foundPathsOrEmpty: string[] = await findResult.unwrapOr([]);
+```

houston-common-lib/lib/defaultconfigs/hl4/index.ts

@@ -0,0 +1,4 @@
+import smbconf from "./smb.conf?raw";
+import zfsconf from "./zfs.json";
+
+export { smbconf, zfsconf }

houston-common-lib/lib/defaultconfigs/hl4/smb.conf

@@ -0,0 +1,5 @@
+[global]
+
+
+[share]
+    path = /tank

houston-common-lib/lib/defaultconfigs/hl4/zfs.json

@@ -0,0 +1 @@
+{}

houston-common-lib/lib/defaultconfigs/index.ts

@@ -0,0 +1 @@
+export * as hl4 from "./hl4"

houston-common-lib/lib/houston.ts

@@ -12,6 +12,8 @@ export * from "@/user";
 export * from "@/group";
 export * from "@/filesystem";
 
+export const server = new Server();
+
 export function getServer(host: string = "localhost"): ResultAsync<Server, ProcessError> {
   const server = new Server(host);
   return server.isAccessible().map(() => server);

houston-common-lib/lib/index.ts

@@ -32,6 +32,7 @@ export * from "@/download";
 export * from "@/upload";
 export * from "@/functional";
 export * from "@/unwrap";
+export * from "@/managers";
 
 export * as legacy from "@/legacy";
 

houston-common-lib/lib/managers/easysetup/manager.ts

@@ -0,0 +1,50 @@
+import { okAsync, Result, ResultAsync } from "neverthrow";
+import { EasySetupConfig } from "./types";
+import { ParsingError, ProcessError, SambaConfParser, SambaManagerNet } from "@/index";
+import * as defaultConfigs from "@/defaultconfigs";
+
+export interface IEasySetupConfigurator {
+
+  applyConfig(config: EasySetupConfig): ResultAsync<void, ProcessError>;
+}
+
+export class EasySetupConfigurator implements IEasySetupConfigurator {
+  sambaManager: SambaManagerNet;
+
+  constructor() {
+    this.sambaManager = new SambaManagerNet();
+  }
+
+  applyConfig(config: EasySetupConfig): ResultAsync<void, ProcessError> {
+
+    return this.applyZFSConfig(config)
+      .andThen(() => this.applySambaConfig(config));
+  }
+
+  private applyZFSConfig(config: EasySetupConfig) {
+    return okAsync({});
+  }
+
+  private applySambaConfig(config: EasySetupConfig) {
+    const globalSambaUpdateResult = this.sambaManager.editGlobal(config.sambaConfig.global);
+    const shareSamabaResults = config.sambaConfig.shares.map(share => this.sambaManager.addShare(share));
+
+    return ResultAsync.combine([
+      globalSambaUpdateResult,
+      ...shareSamabaResults
+    ]).map(() => { });
+  }
+
+  static loadConfig(easyConfigName: keyof typeof defaultConfigs): Result<EasySetupConfig, ParsingError> {
+    const dc = defaultConfigs[easyConfigName];
+    return SambaConfParser()
+      .apply(dc.smbconf)
+      .map((sambaConfig) => {
+        return {
+          sambaConfig,
+          zfsConfig: dc.zfsconf
+        }
+      })
+
+  }
+}

houston-common-lib/lib/managers/easysetup/types.ts

@@ -0,0 +1,5 @@
+import { SambaConfig } from "../samba/types";
+
+export type EasySetupConfig = {
+  sambaConfig: SambaConfig
+};

houston-common-lib/lib/managers/index.ts

@@ -0,0 +1,3 @@
+export * from "./samba/manager";
+export * from "./samba/types";
+export * from "./samba/parser";

houston-common-lib/lib/managers/samba/manager.test.ts

@@ -0,0 +1,57 @@
+import { ParsingError, ProcessError } from "@/errors";
+import { SambaGlobalConfig, SambaShareConfig } from "@/typedoc.index";
+import { errAsync, ResultAsync } from "neverthrow";
+import { SambaManagerBase } from "./manager";
+import { suite, test, expect } from "vitest";
+
+class SambaManagerTest extends SambaManagerBase {
+  addShare(_: SambaShareConfig): ResultAsync<SambaShareConfig, ParsingError | ProcessError> {
+    return errAsync(new Error());
+  }
+
+  editGlobal(
+    _: SambaGlobalConfig
+  ): ResultAsync<SambaGlobalConfig, ParsingError | ProcessError> {
+    return errAsync(new Error());
+  }
+
+  editShare(_: SambaShareConfig): ResultAsync<SambaShareConfig, ParsingError | ProcessError> {
+    return errAsync(new Error());
+  }
+
+  exportConfig(): ResultAsync<string, ProcessError> {
+    return errAsync(new Error());
+  }
+
+  getGlobalConfig(): ResultAsync<SambaGlobalConfig, ParsingError | ProcessError> {
+    return errAsync(new Error());
+  }
+
+  getShare(_: string): ResultAsync<SambaShareConfig, ParsingError | ProcessError> {
+    return errAsync(new Error());
+  }
+
+  getShares(): ResultAsync<SambaShareConfig[], ParsingError | ProcessError> {
+    return errAsync(new Error());
+  }
+
+  importConfig(_: string): ResultAsync<this, ProcessError> {
+    return errAsync(new Error());
+  }
+
+  listShareNames(): ResultAsync<string[], ParsingError | ProcessError> {
+    return errAsync(new Error());
+  }
+
+  removeShare(_: SambaShareConfig): ResultAsync<SambaShareConfig, ParsingError | ProcessError> {
+    return errAsync(new Error());
+  }
+}
+
+suite("SambaManager", () => {
+  const mgr = new SambaManagerTest();
+  test("recommended defaults from conf file", () => {
+    expect(mgr.recommendedGlobalDefaults().isOk()).toBe(true);
+    expect(mgr.recommendedShareDefaults().isOk()).toBe(true);
+  });
+});