Merge remote-tracking branch 'origin/main' into APL-1041

Author: svcAPLBot

docs/gitops.md

@@ -212,3 +212,125 @@ sequenceDiagram
     API-->>Client: HTTP 409
     deactivate API
 ```
+
+## Version three - Git Worktrees
+
+The git worktrees implementation eliminates the performance bottleneck of cloning from remote repository for each request. Instead, a main repository is maintained locally and git worktrees are created for each session. This provides instant session creation while maintaining complete isolation between concurrent operations.
+
+**Key improvements:**
+- Main repository cloned once at startup, eliminating remote clone overhead
+- Git worktrees created instantly from local main repository
+- Each session operates on an isolated branch with independent `.git/index.lock` files
+- Direct push from session branch to main branch on remote
+- Automatic cleanup of worktrees and branches after completion
+- No blocking operations between concurrent sessions due to isolated git indexes
+
+```mermaid
+sequenceDiagram
+     autonumber
+     participant Client1 as Client 1
+     participant Client2 as Client 2
+     participant API as API Server
+     participant MainRepo as Main Git Repo
+     participant Worktree1 as Session Worktree 1
+     participant Worktree2 as Session Worktree 2
+     participant Remote as Remote Git Repository
+
+
+     Note over API,MainRepo: Application Startup
+     API->>MainRepo: Initialize main repo (clone/pull)
+     activate MainRepo
+     MainRepo-->>API: Ready
+
+
+     Note over Client1,Remote: Concurrent API Requests
+     Client1->>API: POST/PUT/DELETE Request
+     activate API
+     API->>API: Generate sessionId (UUID)
+     API->>MainRepo: createWorktree(sessionId, main)
+     MainRepo->>Worktree1: git worktree add -b sessionId path main
+     activate Worktree1
+     Worktree1-->>MainRepo: Session branch created
+     MainRepo-->>API: Worktree repo instance
+     API-->>Client1: Processing...
+
+
+     Client2->>API: POST/PUT/DELETE Request (concurrent)
+     API->>API: Generate sessionId (UUID)
+     API->>MainRepo: createWorktree(sessionId2, main)
+     MainRepo->>Worktree2: git worktree add -b sessionId2 path main
+     activate Worktree2
+     Worktree2-->>MainRepo: Session branch created
+     MainRepo-->>API: Worktree repo instance
+     API-->>Client2: Processing...
+
+
+     Note over Worktree1,Remote: Session 1 Operations
+     API->>Worktree1: writeFile(), modify configs
+     API->>Worktree1: commit("otomi-api commit by user1")
+     Worktree1->>Worktree1: git add . && git commit
+     API->>Worktree1: save() - pull/push with retry
+     loop Retry on conflicts
+         Worktree1->>Remote: git pull origin main --rebase
+         Remote-->>Worktree1: Latest changes
+         Worktree1->>Remote: git push origin sessionId:main
+         alt Push successful
+             Remote-->>Worktree1: Success
+         else Push failed (conflict)
+             Remote-->>Worktree1: Conflict - retry
+         end
+     end
+
+
+     Note over Worktree2,Remote: Session 2 Operations (parallel)
+     API->>Worktree2: writeFile(), modify configs
+     API->>Worktree2: commit("otomi-api commit by user2")
+     Worktree2->>Worktree2: git add . && git commit
+     API->>Worktree2: save() - pull/push with retry
+     loop Retry on conflicts
+         Worktree2->>Remote: git pull origin main --rebase
+         Remote-->>Worktree2: Latest changes + Session1 commits
+         Worktree2->>Remote: git push origin sessionId2:main
+         alt Push successful
+             Remote-->>Worktree2: Success
+         else Push failed (conflict)
+             Remote-->>Worktree2: Conflict - retry
+         end
+     end
+
+
+     Note over API,Remote: Cleanup
+     API->>MainRepo: removeWorktree(sessionId)
+     MainRepo->>Worktree1: git worktree remove path
+     deactivate Worktree1
+     MainRepo-->>API: Worktree removed (branch auto-deleted)
+     API-->>Client1: Response
+
+
+     API->>MainRepo: removeWorktree(sessionId2)
+     MainRepo->>Worktree2: git worktree remove path2
+     deactivate Worktree2
+     MainRepo-->>API: Worktree removed (branch auto-deleted)
+     API-->>Client2: Response
+
+
+     deactivate API
+     deactivate MainRepo
+
+
+     Note over Client1,Remote: Result: No slow remote cloning per request
+     Note over Client1,Remote: Result: Instant worktree creation from local repo
+     Note over Client1,Remote: Each session worked on isolated branch
+     Note over Client1,Remote: Direct push to main: sessionBranch:main
+     Note over Client1,Remote: No index.lock conflicts between sessions
+```
+
+**Git Index Isolation:**
+Version two avoided `.git/index.lock` conflicts by cloning the entire repository from remote to separate directories for each session. While this provided isolation, it created a significant performance bottleneck due to repeated remote cloning.
+
+Git worktrees provide the same isolation benefits but with instant creation from a local repository:
+- Main repo: `.git/index` and `.git/index.lock`  
+- Worktree 1: `.git/worktrees/sessionId1/index` and `.git/worktrees/sessionId1/index.lock`
+- Worktree 2: `.git/worktrees/sessionId2/index` and `.git/worktrees/sessionId2/index.lock`
+
+This maintains the concurrency benefits of version two while eliminating the remote cloning performance penalty.

package.json

@@ -141,7 +141,7 @@
     "cz": "git-cz",
     "cz:retry": "git-cz --retry",
     "dev": "run-p watch dev:node",
-    "dev:node": "export $(grep -v '^#' .env | xargs) && tsx watch --inspect=4321 src/app.ts",
+    "dev:node": "tsx watch --env-file=.env --inspect=4321 src/app.ts",
     "lint": "run-p types lint:ts",
     "lint:ts": "eslint --ext ts .",
     "lint:fix": "eslint --ext ts --fix .",

src/api.test.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-empty-function */
 import * as getValuesSchemaModule from './utils'
 import OpenAPISchemaValidator from 'openapi-schema-validator'
 import { getSpec } from 'src/app'

src/authz.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/ban-ts-comment */
 import { Ability, Subject, subject } from '@casl/ability'
 import Debug from 'debug'
 import { each, forIn, get, isEmpty, isEqual, omit, set } from 'lodash'

src/git.ts

@@ -419,11 +419,56 @@ export class Git {
   async push(): Promise<any> {
     if (!this.url && this.isRootClone()) return
     debug('Pushing')
-    const summary = await this.git.push(this.remote, this.branch)
-    debug('Pushed. Summary: ', summary)
+
+    // For worktrees, push current branch (session branch) to main branch
+    // For main repo, push normally
+    if (!this.isRootClone()) {
+      const currentBranch = await this.git.revparse(['--abbrev-ref', 'HEAD'])
+      const summary = await this.git.push([this.remote, `${currentBranch}:${this.branch}`])
+      debug('Pushed session branch to main. Summary: ', summary)
+    } else {
+      // Original push logic for main repo
+      const summary = await this.git.push(this.remote, this.branch)
+      debug('Pushed. Summary: ', summary)
+    }
     return
   }
 
+  async createWorktree(worktreePath: string, branch: string = this.branch): Promise<void> {
+    debug(`Creating worktree at: ${worktreePath} from branch: ${branch}`)
+    await ensureDir(dirname(worktreePath), { mode: 0o744 })
+
+    // Use sessionId as branch name (from worktree path)
+    const sessionId = basename(worktreePath)
+    const sessionBranch = sessionId
+
+    // Create worktree with session branch
+    await this.git.raw(['worktree', 'add', '-b', sessionBranch, worktreePath, branch])
+    debug(`Worktree created successfully at: ${worktreePath} on branch: ${sessionBranch}`)
+  }
+
+  async removeWorktree(worktreePath: string): Promise<void> {
+    debug(`Removing worktree at: ${worktreePath}`)
+    try {
+      await this.git.raw(['worktree', 'remove', worktreePath])
+      debug(`Worktree removed successfully: ${worktreePath}`)
+    } catch (error) {
+      const errorMessage = getSanitizedErrorMessage(error)
+      debug(`Error removing worktree: ${errorMessage}`)
+      try {
+        await this.git.raw(['worktree', 'remove', '--force', worktreePath])
+        debug(`Worktree force removed: ${worktreePath}`)
+      } catch (err) {
+        const errMessage = getSanitizedErrorMessage(err)
+        debug(`Failed to force remove worktree: ${errMessage}`)
+        if (await pathExists(worktreePath)) {
+          rmSync(worktreePath, { recursive: true, force: true })
+          debug(`Manually removed worktree directory: ${worktreePath}`)
+        }
+      }
+    }
+  }
+
   async getCommitSha(): Promise<string> {
     return this.git.revparse('HEAD')
   }
@@ -479,6 +524,23 @@ export class Git {
   }
 }
 
+export async function getWorktreeRepo(
+  mainRepo: Git,
+  worktreePath: string,
+  branch: string = mainRepo.branch,
+): Promise<Git> {
+  debug(`Creating worktree repo at: ${worktreePath}`)
+
+  await mainRepo.createWorktree(worktreePath, branch)
+
+  const worktreeRepo = new Git(worktreePath, mainRepo.url, mainRepo.user, mainRepo.email, mainRepo.urlAuth, branch)
+
+  await worktreeRepo.addConfig()
+  await worktreeRepo.initSops()
+
+  return worktreeRepo
+}
+
 export default async function getRepo(
   path: string,
   url: string,

src/middleware/error.ts

@@ -1,4 +1,3 @@
-/* eslint-disable no-param-reassign */
 import { debug, error } from 'console'
 import { Response } from 'express'
 import { HttpError, OtomiError } from 'src/error'
@@ -9,7 +8,7 @@ import { cleanSession } from './session'
 const env = cleanEnv({})
 
 // Note: 4 arguments (no more, no less) must be defined in your errorMiddleware function. Otherwise the function will be silently ignored.
-// eslint-disable-next-line no-unused-vars
+
 export function errorMiddleware(e, req: OpenApiRequest, res: Response, next): void {
   if (env.isDev) error('errorMiddleware error', e)
   else debug('errorMiddleware error', e)

src/middleware/session.ts

@@ -11,6 +11,7 @@ import { OpenApiRequestExt } from 'src/otomi-models'
 import { default as OtomiStack, rootPath } from 'src/otomi-stack'
 import { cleanEnv, EDITOR_INACTIVITY_TIMEOUT } from 'src/validators'
 import { v4 as uuidv4 } from 'uuid'
+import { getSanitizedErrorMessage } from '../utils'
 
 const debug = Debug('otomi:session')
 const env = cleanEnv({
@@ -41,8 +42,7 @@ export const setSessionStack = async (editor: string, sessionId: string): Promis
   if (!sessions[sessionId]) {
     debug(`Creating session ${sessionId} for user ${editor}`)
     sessions[sessionId] = new OtomiStack(editor, sessionId)
-    // init repo without inflating values from files as its faster to copy the values
-    await sessions[sessionId].initGit(false)
+    await sessions[sessionId].initGitWorktree(readOnlyStack.git)
     sessions[sessionId].repoService = cloneDeep(readOnlyStack.repoService)
   } else sessions[sessionId].sessionId = sessionId
   return sessions[sessionId]
@@ -59,8 +59,20 @@ export const cleanAllSessions = (): void => {
 
 export const cleanSession = async (sessionId: string): Promise<void> => {
   debug(`Cleaning session ${sessionId}`)
+  const session = sessions[sessionId]
+  const worktreePath = join(rootPath, sessionId)
+  if (session?.git) {
+    try {
+      await readOnlyStack.git.removeWorktree(worktreePath)
+    } catch (error) {
+      const errorMessage = getSanitizedErrorMessage(error)
+      debug(`Error removing worktree for session ${sessionId}: ${errorMessage}`)
+      await remove(worktreePath)
+    }
+  } else {
+    await remove(worktreePath)
+  }
   delete sessions[sessionId]
-  await remove(join(rootPath, sessionId))
 }
 
 let io: Server
@@ -98,6 +110,7 @@ export function sessionMiddleware(server: http.Server): RequestHandler {
     if (['post', 'put', 'delete'].includes(req.method.toLowerCase())) {
       // in the workloadCatalog endpoint(s), don't need to create a session
       if (req.path === '/v1/workloadCatalog' || req.path === '/v1/createWorkloadCatalog') return next()
+
       // bootstrap session stack with unique sessionId to manipulate data
       const sessionId = uuidv4() as string
       // eslint-disable-next-line no-param-reassign

src/otomi-stack.ts

@@ -1,4 +1,4 @@
-import { CoreV1Api, User as k8sUser, KubeConfig, V1ObjectReference } from '@kubernetes/client-node'
+import { CoreV1Api, KubeConfig, User as k8sUser, V1ObjectReference } from '@kubernetes/client-node'
 import Debug from 'debug'
 
 import { getRegions, ObjectStorageKeyRegions } from '@linode/api-v4'
@@ -9,7 +9,7 @@ import { generate as generatePassword } from 'generate-password'
 import { cloneDeep, filter, isEmpty, map, mapValues, merge, omit, pick, set, unset } from 'lodash'
 import { getAppList, getAppSchema, getSpec } from 'src/app'
 import { AlreadyExists, ForbiddenError, HttpError, OtomiError, PublicUrlExists, ValidationError } from 'src/error'
-import getRepo, { Git } from 'src/git'
+import getRepo, { getWorktreeRepo, Git } from 'src/git'
 import { cleanSession, getSessionStack } from 'src/middleware'
 import {
   AplBackupRequest,
@@ -329,6 +329,25 @@ export default class OtomiStack {
     debug(`Values are loaded for ${this.editor} in ${this.sessionId}`)
   }
 
+  async initGitWorktree(mainRepo: Git): Promise<void> {
+    await this.init()
+    debug(`Creating worktree for session ${this.sessionId}`)
+
+    try {
+      await mainRepo.git.revparse(`--verify refs/heads/${env.GIT_BRANCH}`)
+    } catch (error) {
+      const errorMessage = getSanitizedErrorMessage(error)
+      throw new Error(
+        `Main repository does not have branch '${env.GIT_BRANCH}'. Cannot create worktree. ${errorMessage}`,
+      )
+    }
+
+    const worktreePath = this.getRepoPath()
+    this.git = await getWorktreeRepo(mainRepo, worktreePath, env.GIT_BRANCH)
+
+    debug(`Worktree created for ${this.editor} in ${this.sessionId}`)
+  }
+
   getSecretPaths(): string[] {
     // we split secrets from plain data, but have to overcome teams using patternproperties
     const teamProp = 'teamConfig.patternProperties.^[a-z0-9]([-a-z0-9]*[a-z0-9])+$'
@@ -1950,8 +1969,10 @@ export default class OtomiStack {
     try {
       // Commit and push Git changes
       await this.git.save(this.editor!, encryptSecrets, files)
+      // Pull the latest changes to ensure we have the most recent state
+      await rootStack.git.git.pull()
 
-      // Execute the provided action dynamically
+      // Update the team configuration of the root stack
       action(rootStack.repoService.getTeamConfigService(teamId))
 
       debug(`Updated root stack values with ${this.sessionId} changes`)
@@ -1974,8 +1995,9 @@ export default class OtomiStack {
     try {
       // Commit and push Git changes
       await this.git.save(this.editor!, encryptSecrets, files)
-
-      // Execute the provided action dynamically
+      // Pull the latest changes to ensure we have the most recent state
+      await rootStack.git.git.pull()
+      // update the repo configuration of the root stack
       action(rootStack.repoService)
 
       debug(`Updated root stack values with ${this.sessionId} changes`)

src/utils/workloadUtils.test.ts

@@ -183,7 +183,6 @@ describe('fetchChartYaml', () => {
 
     const result = await fetchChartYaml(url)
 
-    // eslint-disable-next-line @typescript-eslint/unbound-method
     expect(axios.get).toHaveBeenCalledWith(
       'https://raw.githubusercontent.com/owner/repo/main/charts/mychart/Chart.yaml',
       { responseType: 'text' },
@@ -197,7 +196,7 @@ describe('fetchChartYaml', () => {
     const result = await fetchChartYaml(url)
 
     expect(result).toEqual({ values: {}, error: 'Unsupported Git provider or invalid URL format.' })
-    // eslint-disable-next-line @typescript-eslint/unbound-method
+
     expect(axios.get).not.toHaveBeenCalled()
   })