pkg/

directory
v1.0.0-beta.109 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 14, 2026 License: MIT

README

Util

Utility packages providing common functionality across the SemStreams platform.

Overview

The util package contains a collection of utility subpackages that provide common, reusable functionality used throughout the SemStreams codebase. Each subpackage focuses on a specific utility domain, maintaining clear separation of concerns.

Subpackages

timestamp

High-precision timestamp utilities for temporal operations and synchronization.

import "github.com/c360/semstreams/pkg/util/timestamp"

Key features:

  • Microsecond precision timestamps
  • RFC3339 formatting with microseconds
  • Time comparison utilities
  • Clock synchronization helpers
  • Temporal indexing support

See timestamp README for detailed documentation.

Architecture

The util package follows a subpackage organization pattern where:

  • Single Responsibility: Each subpackage handles one specific utility domain
  • No Cross-Dependencies: Utility subpackages don't depend on each other
  • Zero External Dependencies: Utilities rely only on Go standard library where possible
  • Performance First: Utilities are optimized for high-frequency use

Usage Pattern

Utility subpackages are imported directly by packages that need specific functionality:

import (
    "github.com/c360/semstreams/pkg/util/timestamp"
)

// Use timestamp utilities
now := timestamp.Now()
formatted := timestamp.Format(now)

Design Decisions

Subpackage Organization: We organize utilities into subpackages rather than a flat structure because:

  • Prevents util from becoming a "junk drawer" of unrelated functions
  • Makes dependencies explicit and trackable
  • Allows utilities to evolve independently
  • Improves code organization and discoverability

Minimal Dependencies: Utilities minimize external dependencies to:

  • Reduce coupling across the codebase
  • Improve testability
  • Ensure predictable performance
  • Simplify deployment and compilation

Guidelines for New Utilities

When adding new utility subpackages:

  1. Single Purpose: Each subpackage should have one clear purpose
  2. No Business Logic: Utilities should be domain-agnostic
  3. Well Tested: Minimum 90% test coverage with edge cases
  4. Documented: Complete API documentation with examples
  5. Performance: Benchmark critical paths

License

MIT

Directories

Path Synopsis
Package acme provides ACME client functionality for automated certificate management
 Package acme provides ACME client functionality for automated certificate management
Package buffer provides generic, thread-safe buffer implementations with various overflow policies.
 Package buffer provides generic, thread-safe buffer implementations with various overflow policies.
Package cache provides generic, thread-safe cache implementations with various eviction policies.
 Package cache provides generic, thread-safe cache implementations with various eviction policies.
Package context provides building blocks for context construction in agentic systems.
 Package context provides building blocks for context construction in agentic systems.
Package dispatch provides the BoundedDispatcher substrate primitive — a bounded-concurrency parallel worker pool with optional KV-twofer-aware completion handling.
 Package dispatch provides the BoundedDispatcher substrate primitive — a bounded-concurrency parallel worker pool with optional KV-twofer-aware completion handling.
Package errs provides standardized error handling patterns for SemStreams components.
 Package errs provides standardized error handling patterns for SemStreams components.
Package lifecycle provides a substrate convention layer for workflow-shaped entities — named instances with declared phases, restart recovery, operator visibility, and rule integration.
 Package lifecycle provides a substrate convention layer for workflow-shaped entities — named instances with declared phases, restart recovery, operator visibility, and rule integration.
Package logging provides slog handlers for structured logging with multi-destination support, NATS publishing, and graceful fallback behavior.
 Package logging provides slog handlers for structured logging with multi-destination support, NATS publishing, and graceful fallback behavior.
Package ownership implements the ADR-056 authoritative-semantic-state owner registry: the framework substrate that names exactly one owner per (entity-ID pattern, predicate group) and rejects two owners selecting the same cell in an owning write mode.
 Package ownership implements the ADR-056 authoritative-semantic-state owner registry: the framework substrate that names exactly one owner per (entity-ID pattern, predicate group) and rejects two owners selecting the same cell in an owning write mode.
Package platform holds the platform-identity struct used across the SemStreams codebase.
 Package platform holds the platform-identity struct used across the SemStreams codebase.
Package projection implements the ADR-056 Decision 6 graph projection contract — the missing middle layer between "what type is flowing" (the payload registry) and "who may author these facts at runtime" (pkg/ownership).
 Package projection implements the ADR-056 Decision 6 graph projection contract — the missing middle layer between "what type is flowing" (the payload registry) and "who may author these facts at runtime" (pkg/ownership).
Package resource provides utilities for monitoring resource availability.
 Package resource provides utilities for monitoring resource availability.
Package retry provides simple exponential backoff retry logic for transient failures.
 Package retry provides simple exponential backoff retry logic for transient failures.
Package security provides platform-wide security configuration types
 Package security provides platform-wide security configuration types
Package swecommon provides schema-bound encoders and decoders for the OGC SWE Common data model, covering the JSON, text, and binary encodings the OGC Connected Systems API negotiates for observation results and command payloads.
 Package swecommon provides schema-bound encoders and decoders for the OGC SWE Common data model, covering the JSON, text, and binary encodings the OGC Connected Systems API negotiates for observation results and command payloads.
Package text provides text manipulation utilities.
 Package text provides text manipulation utilities.
Package timestamp provides standardized Unix timestamp handling utilities.
 Package timestamp provides standardized Unix timestamp handling utilities.
Package tlsutil provides TLS configuration utilities for secure connections.
 Package tlsutil provides TLS configuration utilities for secure connections.
Package types provides core type definitions for the semantic event mesh.
 Package types provides core type definitions for the semantic event mesh.
Package worker provides a generic, thread-safe worker pool for concurrent task processing.
 Package worker provides a generic, thread-safe worker pool for concurrent task processing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.