tkInfra

Infrastructure

Infrastructure layer of Infinite Toolkit (TK). It implements I/O: file, shell, network, crypto, and database helpers, plus the repository implementations. It depends on the domain layer and never on presentation. Part of Infinite Toolkit.

Helpers

• Deserializer: Deserialize JSON and YAML files into maps for configuration handling.

  deserializedMap, deserializationErr := StringDeserializer(
    `{"name": "test", "value": 123}`, SerializationFormatJson,
  )
  
  deserializedMap, deserializationErr := StringDeserializer(
    "name: test\nvalue: 123", SerializationFormatYaml,
  )
  
  deserializedMap, deserializationErr := FileDeserializer("config.json")
  

• FileClerk: Perform file operations including existence checks, creation, copying, reading content, regex search and replace, atomic overwrite-rename, collision-safe temp file naming, symlink-safe directory listing and search, and symlink handling.

  clerk := FileClerk{}
  
  // ExistenceChecks
  isFileExists := clerk.FileExists("example.txt")
  isRegularFile := clerk.IsFile("example.txt")
  isDirectoryExists := clerk.IsDir("example_dir")
  isSymlink := clerk.IsSymlink("symlink.txt")
  isSymlinkToTarget := clerk.IsSymlinkTo("symlink.txt", "target.txt")
  
  // FileCreation
  fileCreationErr := clerk.TouchFile("example.txt")
  
  // FileContentOperations
  maxContentSize := int64(1024)
  fileContent, fileReadingErr := clerk.ReadFileContent("example.txt", &maxContentSize)
  regexSearchFilePath, regexSearchFilePathErr := tkValueObject.NewUnixAbsoluteFilePath("example.txt", false)
  regexPattern := regexp.MustCompile(`(?m)^error: (.+)$`)
  regexSearchFindings, regexSearchErr := clerk.FileContentRegexSearch(regexSearchFilePath, regexPattern)
  regexReplacement := `warn: $1`
  replacementCount, regexReplaceErr := clerk.FileContentRegexReplace(
    FileRegexReplaceSettings{FilePath: regexSearchFilePath},
    regexPattern, regexReplacement,
  )
  fileAppendErr := clerk.AppendFileContent(
    FileAppendSettings{FilePath: regexSearchFilePath}, "new content",
  )
  fileTruncationErr := clerk.TruncateFileContent(regexSearchFilePath)
  
  // DirectoryReading
  listDirPath, listDirPathErr := tkValueObject.NewUnixAbsoluteFilePath(
    "/var/www", false,
  )
  unixFiles, listDirErr := clerk.ListDir(FileListDirSettings{
    DirPath:  listDirPath,
    MaxDepth: 1,
  })
  namePattern := regexp.MustCompile(`\.conf$`)
  findStartingPathPattern, findStartingPathPatternErr := tkValueObject.NewUnixAbsoluteGlobPath(
    "/var/www/*/conf",
  )
  foundFiles, findErr := clerk.Find(FileFindSettings{
    StartingPathPattern: findStartingPathPattern,
    MaxDepth:            3,
    NamePattern:         namePattern,
  })
  
  // FileManipulation
  fileCopyErr := clerk.CopyFile("source.txt", "destination.txt")
  fileMoveErr := clerk.MoveFile("old.txt", "new.txt")
  fileOverwriteErr := clerk.OverwriteFile("source.tmp", "destination.txt")
  fileDeletionErr := clerk.DeleteFile("example.txt")
  
  // FileAdvancedOperations
  fileOwnershipUpdateErr := clerk.UpdateFileOwnership("example.txt", 1000, 1000)
  filePermissions := 0755
  filePermissionsUpdateErr := clerk.UpdateFilePermissions("example.txt", &filePermissions)
  ownerUsername, ownerUsernameErr := tkValueObject.NewUnixUsername("example")
  serviceFilePath, serviceFilePathErr := tkValueObject.NewUnixAbsoluteFilePath(
    "/home/example/.config/systemd/user/service.service", false,
  )
  serviceFilePermissions := os.FileMode(0644)
  fileUpsertErr := clerk.UpsertFile(FileUpsertSettings{
    FilePath:                 serviceFilePath,
    OverwritePolicy:          &FileClerkOverwritePolicyReplace,
    TrustedDirOwnerUsernames: []tkValueObject.UnixUsername{ownerUsername},
    Permissions:              &serviceFilePermissions,
    OwnerUsername:            &ownerUsername,
  }, []byte("unit content"))
  
  // CompressionOperations
  compressionFormat := "gzip"
  compressedFilePath, compressionErr := clerk.CompressFile(
    "example.txt", &compressionFormat,
  )
  decompressionTargetPath := "decompressed.txt"
  shouldKeepSourceFile := false
  decompressedFilePath, decompressionErr := clerk.DecompressFile(
    "example.txt.tar", &decompressionTargetPath, &shouldKeepSourceFile,
  )
  
  // DirectoryOperations
  directoryCreationErr := clerk.CreateDir("example_dir")
  directoryCopyErr := clerk.CopyDir("source_dir", "dest_dir")
  directoryMoveErr := clerk.MoveDir("old_dir", "new_dir")
  directoryDeletionErr := clerk.DeleteDir("example_dir")
  directoryCompressionFormat := "brotli"
  directoryCompressionErr := clerk.CompressDir(
    "example_dir", &directoryCompressionFormat,
  )
  directoryDecompressionTargetPath := "decompressed_dir"
  shouldKeepSourceDir := true
  directoryDecompressionErr := clerk.DecompressDir(
    "example_dir.tar", &directoryDecompressionTargetPath, &shouldKeepSourceDir,
  )
  
  // SymlinkOperations
  shouldOverwriteSymlink := false
  symlinkCreationErr := clerk.CreateSymlink(
    "target.txt", "symlink.txt", shouldOverwriteSymlink,
  )
  symlinkRemovalErr := clerk.RemoveSymlink("symlink.txt")
  

  UpsertFile Notes

  UpsertFile writes through a held parent-directory handle and defaults to the safe policies: it refuses symlinked paths, refuses to replace an existing target, creates new files as FileClerkDefaultNewFileMode (0600), and inherits the target's mode and owner on replace. Callers opt in with FileClerkSymlinkPolicyResolve, FileClerkOverwritePolicyReplace, and a FileClerkOwnerSource; TrustedDirOwnerUsernames and TrustedDirOwnerUserIds name the trusted directory owners. Every parent component must be owned by root or by one of them (ErrDirectoryOwnerInvalid names the offending component). When the set is empty, the walk trusts the running process account and root. Name a third-party owner only when you trust it. DirChainPolicy defaults to FileClerkDirChainPolicySharedWriteAllowed; FileClerkDirChainPolicySharedWriteRefused also rejects any parent component that group or others can write, unless it is sticky (ErrDirectoryWritableByOthers). A stated owner wins over the existing-file source and conflicts with the other sources (ErrOwnerSourceConflict); a stated group or mode wins, and an omitted mode inherits the target or defaults to 0600 on create. A directory target fails with ErrTargetIsDirectory, and a process that cannot set the resolved owner fails with ErrFileOwnerChangeFailed.

  FileContentRegexReplace and AppendFileContent Notes

  FileContentRegexReplace takes FileRegexReplaceSettings and uses the same trust model as UpsertFile: it walks the parent directory chain through a held handle, opens the target through that handle, verifies the opened inode, and preserves the target's owner, group, and mode (special bits included). It refuses symlinks unless SymlinkPolicy resolves them. Empty files and directories are rejected. AppendFileContent verifies the opened inode and only appends to an existing file through an O_APPEND write, so the target's owner, group, and mode stay untouched and concurrent writers never lose data. A missing target fails with ErrFileMissing; create it with UpsertFile first. FileAppendSettings takes SymlinkPolicy, DirChainPolicy, TrustedDirOwnerUsernames, and TrustedDirOwnerUserIds.

  ListDir and Find Notes

  ListDir and Find read directory trees into []tkEntity.UnixFile entities. They use the same trust model as UpsertFile. The root directory chain is walked through held handles, so a path swap cannot redirect the read. Every opened subdirectory is checked against its inspected inode.

  MaxDepth 0 reads only the root's entries. MaxDepth N reads N levels of subdirectories. MaxFiles caps the returned entities and each directory read. A nil MaxFiles uses FileClerkDefaultMaxFiles (1000). A MaxFiles of 0 reads without a cap. A small cap truncates the result silently. Raise the cap, or pass 0, when the result must be complete.

  Find takes exactly one of two starting points. StartingPath (type UnixAbsoluteFilePath) is a single directory walked as-is. StartingPathPattern (type UnixAbsoluteGlobPath) accepts the glob wildcards *, ?, and [], for example /var/home/*/Downloads, and every directory it matches is walked. A wildcard pattern that matches nothing returns an empty result. A starting path that does not exist fails with ErrDirMissing. Paths that are not directories are skipped. A wildcard match that cannot be read is skipped and a warning names it; a starting path that is named directly fails with its read error. Setting both starting points fails with ErrStartingPathConflict; setting neither fails with ErrStartingPathMissing. A symlinked starting directory fails the search under the default policy; pass a resolving SymlinkPolicy to walk it. Find also takes an optional NamePattern regex. The regex matches the entry name, not the path. A nil NamePattern matches every entry. ListDir sorts by entry name and the path breaks ties. Find sorts by path. The MaxFiles cap counts across all matched starting directories.

  A symlinked root path is refused unless SymlinkPolicy resolves it. The walk reports an entry symlink and never descends into it.

  An entry that cannot become an entity is skipped and logged at debug level. This happens when the value object rejects the name, or when the owner or group has no account. An entry the walk cannot stat, or a subdirectory it cannot open, is skipped and a warning names it. A subdirectory removed during the walk is skipped and logged at debug level. A subdirectory replaced during the walk fails with ErrTargetFileChanged. A missing directory fails with ErrDirMissing.

• Shell: Execute system commands with configurable user, timeout, environment variables, and output redirection to files.

  shell := NewShell(ShellSettings{
      Command: "echo",
      Args:    []string{"hello world"},
  })
  commandOutput, executionErr := shell.Run()
  fmt.Println(commandOutput)
  

  Set ExecutionTimeoutSecs for a relative timeout, ExecutionDeadline (an absolute UnixTime) for an absolute one, or both. When both are set, the earlier wins. When neither is set, the timeout is 1800 seconds. ShouldDisableTimeout overrides both fields and runs the command without any timeout. UnixTime has 1-second granularity, so a deadline built with NewUnixTimeAfterNow can land up to 1 second earlier than the requested duration. The shell honors the requested value, so a caller that passes an untrusted ExecutionTimeoutSecs must bound it.

  deadline := tkValueObject.NewUnixTimeAfterNow(4 * time.Hour)
  shell := NewShell(ShellSettings{
      Command:              "long-running-task",
      ExecutionTimeoutSecs: 5 * 3600,
      ExecutionDeadline:    &deadline,
  })
  

• ShellEscape: Quote a string for safe interpolation into a POSIX shell command, or strip non-printable characters.

  escapedArg := ShellEscape{}.Quote("hello world")
  printableStr := ShellEscape{}.StripUnsafe("hello\x00world")
  

• Synthesizer: Generate cryptographically secure random integers, passwords with charset guarantees, filler usernames/emails, private keys, and TLS certificates (including CA certificates).

  synthesizer := &Synthesizer{}
  
  randomInteger := synthesizer.RandomIntegerGenerator(1, 100)
  
  password := synthesizer.PasswordFactory(16, true)
  
  randomUsername := synthesizer.UsernameFactory()
  randomEmail := synthesizer.MailAddressFactory(nil)
  
  rsaKeyPem, rsaErr := synthesizer.PrivateKeyPemFactory(PrivateKeySettings{
    Algorithm: tkValueObject.PrivateKeyAlgorithmRSA,
    BitSize:   2048,
  })
  
  ecdsaKeyPem, ecdsaErr := synthesizer.PrivateKeyPemFactory(PrivateKeySettings{
    Algorithm: tkValueObject.PrivateKeyAlgorithmECDSA,
    BitSize:   256, // Supports 256, 384, 521
  })
  
  commonName, _ := tkValueObject.NewFqdn("goinfinite.net")
  aliasName, _ := tkValueObject.NewFqdn("goinfinite.com.br")
  altNames := []tkValueObject.Fqdn{aliasName}
  
  certPair, certGenErr := synthesizer.SelfSignedCertificatePairFactory(
    &commonName, altNames,
  )
  
  certPem, keyPem, certPemGenErr := synthesizer.SelfSignedCertificatePairPemFactory(
    &commonName, altNames,
  )
  
  certPem, keyPem, certErr := synthesizer.CertificatePemFactory(CertificateSettings{
    CommonName: &commonName,
    AltNames:   altNames,
  })
  
  maxPathLen := 2
  caCertPem, caKeyPem, caErr := synthesizer.CACertificatePemFactory(CertificateSettings{
    CommonName:       &commonName,
    MaxPathLengthPtr: &maxPathLen,
  })
  

• ServerIpAddress: Retrieve the server's private and public IP addresses. The public IP read honors SERVER_PUBLIC_IP_ADDR as the primary source of truth before any HTTP lookup.

  privateIpAddress, privateIpReadingErr := ReadServerPrivateIpAddress()
  
  publicIpAddress, publicIpReadingErr := ReadServerPublicIpAddress()
  

• DnsLookup: Perform DNS queries for various record types using custom resolvers with fallback support. Setting ShouldBypassLocalResolver: true skips Go's net.Resolver and issues raw dnsmessage UDP queries to bypass /etc/hosts and resolv.conf (applies to A/AAAA only).

  hostname, _ := tkValueObject.NewUnixHostname("example.com")
  dnsLookup := NewDnsLookup(DnsLookupSettings{
      ShouldBypassLocalResolver: true,
  })
  
  dnsRecords, lookupErr := dnsLookup.Execute(
      hostname, &tkValueObject.DnsRecordTypeA,
  )
  

• TrustedCidrsReader: Parse comma-separated trusted entries from both TRUSTED_IPS and TRUSTED_CIDRS environment variables. Accepts plain IP addresses (converted to /32 for IPv4 and /128 for IPv6) and CIDR notation in either variable. Invalid entries are logged and skipped. Returns []CidrBlock.

  trustedCidrBlocks, trustedCidrsReadingErr := TrustedCidrsReader()
  

• ReadThrough: Read-through utilities for TLS certificate pairs from CERTIFICATE_PAIR_CERT_PATH and CERTIFICATE_PAIR_KEY_PATH env vars, generating self-signed certificates in PKI_DIR if not provided.

  readThrough := &ReadThrough{}
  
  certFilePath, keyFilePath, certPairReadingErr := readThrough.CertPairFilePathsReader()
  

• Cypher: Encrypt and decrypt strings using AES-GCM for authenticated encryption with base64 encoding.

  encodedSecretKey, keyGenerationErr := NewCypherSecretKey()
  
  cypher, cypherCreationErr := NewCypher(encodedSecretKey)
  
  encryptedText, encryptionErr := cypher.Encrypt("plain text")
  
  decryptedText, decryptionErr := cypher.Decrypt(encryptedText)
  

• PaginationQueryBuilder: Build paginated database queries with support for page number, items per page, last seen ID, sorting, and total count.

  databaseQuery := db.Model(&YourModel{})
  
  requestPagination := tkDto.Pagination{
      PageNumber:   0,
      ItemsPerPage: 10,
  }
  
  paginatedQuery, responsePagination, paginationBuildingErr := PaginationQueryBuilder(
    databaseQuery, requestPagination, "",
  )
  
  modelRecords := []YourModel{}
  queryExecutionErr := paginatedQuery.Find(&modelRecords).Error
  

• PaginationPagesTotalResolver: Compute the total page count from an item count and a page size. A zero page size fails with ErrItemsPerPageCannotBeZero; a count above uint32 fails with ErrPagesTotalOverflow. A partial page counts as a page.

  pagesTotal, pagesTotalErr := PaginationPagesTotalResolver(250, 20)
  

• TrailDatabaseService: Initialize and migrate a SQLite trail database for activity records using GORM, configurable via TRAIL_DATABASE_FILE_PATH environment variable.

  os.Setenv("TRAIL_DATABASE_FILE_PATH", "/path/to/trail.db")
  
  trailDatabaseService, serviceInitializationErr := NewTrailDatabaseService(
    []any{&YourAdditionalModel{}},
  )
  
  activityRecords := []ActivityRecord{}
  trailDatabaseService.Handler.Model(&ActivityRecord{}).Find(&activityRecords)
  

• TransientDatabaseService: Initialize a shared in-memory SQLite key-value store with Set, Read, and Has. Every instance in the process shares the same data, which vanishes when the process ends; Read returns ErrKeyNotFound for a missing key. Set accepts an optional time-to-live; pass nil to store an entry that never expires. Read and Has treat an expired entry as missing.

  transientDatabaseService, serviceInitializationErr := NewTransientDatabaseService()
  
  ttl := 5 * time.Minute
  setErr := transientDatabaseService.Set("key", "value", &ttl)
  
  value, readErr := transientDatabaseService.Read("key")
  
  keyExists := transientDatabaseService.Has("key")
  

Repositories

• activityRecord/: GORM implementations of the domain ActivityRecordCmdRepo and ActivityRecordQueryRepo interfaces.