tkPresentation

Presentation

Presentation layer of Infinite Toolkit (TK). It parses untrusted input, wraps responses, and provides Echo middleware. It depends on infra and domain. Part of Infinite Toolkit.

Middleware

• PanicHandler: Handle panics in HTTP requests, log filtered stack traces (excluding domain layers), and respond with error messages; uses TRUSTED_IPS and TRUSTED_CIDRS env vars to mask sensitive information from untrusted operators. It can be used with CLI applications as well. The trust check uses the extracted requester IP. When the whole chain is trusted, that IP is the original requester as recorded by the first proxy. A client on the trusted network can claim another trusted IP by sending its own X-Forwarded-For. Overwrite the header at the proxy to prevent this.

  // ForApiInitialization
  echoInstance.Use(ApiPanicHandler)
  
  // ForCliInitialization
  defer CliPanicHandler()
  

• LogHandler: Configure logging levels via LOG_LEVEL environment variable and initialize structured logging with slog and Zerolog.

Helpers

• RequiredParamsInspector: Check that every required parameter is present in a request input map before further parsing.

  paramsReceived := map[string]any{"name": "John", "age": 30}
  paramsRequired := []string{"name", "email"}
  requiredParamsValidationErr := RequiredParamsInspector(paramsReceived, paramsRequired)
  

• ApiRequestInputReader: Read and parse JSON, form data, or multipart files from Echo HTTP requests into structured data.

  inputReader := ApiRequestInputReader{}
  requestData, requestParsingErr := inputReader.Reader(echoContext)
  

• RequesterIpExtractor: Requester IP extraction with a peer trust gate and a right-to-left trust chain walk. Reads IP_EXTRACT_HEADER env var as a comma-separated ordered chain (default: X-Forwarded-For,X-Real-IP). When RemoteAddr is not a trusted IP (local, private, link-local, or in TRUSTED_IPS/TRUSTED_CIDRS), the extractor returns it and ignores the headers, because the client connected directly. Otherwise each header is walked right-to-left; malformed entries are ignored, and the first entry that is not a trusted IP is returned. When every entry is trusted, the extractor returns the original requester — the first entry of the first header that has one. This matches Echo's RealIP semantics. Otherwise it returns RemoteAddr. The chain supports the special keywords Direct and RemoteAddr to force extraction from http.Request.RemoteAddr.

  Example: a request arrives with X-Forwarded-For: 127.0.0.1 and RemoteAddr: 172.17.0.1:54321. Both addresses are trusted, so the extractor returns 127.0.0.1, not the proxy address.

  Security: The headers are read only from trusted peers: loopback, private, link-local, or in TRUSTED_IPS/TRUSTED_CIDRS. A client on an untrusted network cannot choose the reported address. Right-to-left traversal skips values a client prepends when a trusted proxy appends the real client last. A proxy with a public address must be listed in TRUSTED_CIDRS, or the extractor reports the proxy address. Over-broad TRUSTED_CIDRS is the risk: the extractor would trust a range that includes untrusted clients.

  extractor := NewRequesterIpExtractor()
  
  ipAddress, err := extractor.Execute(httpRequest)
  

• EnvsInspector: Inspect and validate environment variables from .env files loaded via ENV_FILE_PATH env var, supporting required and auto-fillable variables.

  optionalEnvFilePath := "/path/to/.env"
  requiredEnvVarNames := []string{"TRAIL_DATABASE_FILE_PATH", "SESSION_TOKEN_SECRET"}
  autoFillableEnvVars := []string{"SESSION_TOKEN_SECRET"}
  envsInspector := NewEnvsInspector(
    optionalEnvFilePath, requiredEnvVarNames, autoFillableEnvVars,
  )
  envsValidationErr := envsInspector.Inspect()
  

• PaginationParser: Parse pagination parameters like pageNumber, itemsPerPage, lastSeenId, sortBy, and sortDirection from HTTP requests. A zero itemsPerPage fails with InvalidItemsPerPage; a fractional pageNumber or itemsPerPage fails with InvalidPageNumber or InvalidItemsPerPage.

  defaultPagination := tkDto.Pagination{PageNumber: 0, ItemsPerPage: 10}
  untrustedInput := map[string]any{"pageNumber": 1, "itemsPerPage": 20}
  parsedPagination, paginationParsingErr := PaginationParser(
    defaultPagination, untrustedInput,
  )
  

• StringSliceVoParser: Convert comma-separated, semicolon-separated, or array strings into value object slices.

  rawInput := "note1,note2;note3"
  parsedNotes := StringSliceValueObjectParser(rawInput, tkValueObject.NewGenericNotes)
  

• TimeParamsParser: Parse date ranges, timestamps, and relative times from request parameters.

  timeParamNames := []string{"createdAt", "updatedAt"}
  untrustedInput := map[string]any{"createdAt": 1609459200}
  parsedTimeParams := TimeParamsParser(timeParamNames, untrustedInput)
  fmt.Println(parsedTimeParams["createdAt"])
  

• ResponseWrapper: A wrapper struct for liaison responses and when needed, used to emit API and CLI responses.

  apiResponse := NewApiResponseWrapper(201, accountEntity, "AccountCreatedSuccessfully")
  
  liaisonResponse := NewLiaisonResponse(
    LiaisonResponseStatusCreated, accountEntity, "AccountCreatedSuccessfully",
  )
  
  err := errors.New("AccountNotFound")
  
  liaisonResponseNoMessage := NewLiaisonResponseNoMessage(
    LiaisonResponseStatusSuccess, err.Error(),
  )
  
  liaisonApiEmissionErr := LiaisonApiResponseEmitter(echoContext, liaisonResponse)
  
  LiaisonCliResponseRenderer(liaisonResponse)