Merge pull request #6

Add project content for darvaza, kagal, and poupe

Author: amery

content/projects/darvaza-cache.md

@@ -0,0 +1,34 @@
+---
+title: darvaza.org/cache
+description: Generic cache abstraction with TTL, stampede control, and pluggable backends.
+category:
+  - darvaza
+  - go
+repo: github:darvaza-proxy/cache
+licence: MIT
+go: darvaza.org/cache
+---
+
+Generic cache abstraction keyed by any `comparable` type. The
+:go-pkg{mod="darvaza.org/cache" sym="Cache" short} interface
+provides `Get`, `Set`, and `Remove` with per-entry expiration. Data
+flows through a `Sink` abstraction — `ByteSink` for raw bytes,
+`GobSink[T]` for Gob-encoded objects, or a custom `SinkFn[T]` built
+from user-supplied encode/decode functions.
+A :go-pkg{mod="darvaza.org/cache" sym="Store" short} manages named
+cache namespaces with size limits and pluggable data loaders
+(`Getter[K]`).
+
+## Backends
+
+| Backend | Module | Description |
+|---------|--------|-------------|
+| simplelru | :badge-version-go{mod="darvaza.org/cache/x/simplelru"} | Non-thread-safe LRU with TTL; evicts expired entries first |
+| memcache | :badge-version-go{mod="darvaza.org/cache/x/memcache"} | Thread-safe in-memory cache with `SingleFlight` stampede prevention |
+| groupcache | :badge-version-go{mod="darvaza.org/cache/x/groupcache"} | Distributed caching via :go-pkg{mod="github.com/mailgun/groupcache/v2" label="mailgun/groupcache"} with HTTP peer discovery |
+| protosink | :badge-version-go{mod="darvaza.org/cache/x/protosink"} | `TSink[T]` implementation using Protocol Buffers encoding |
+
+## See also
+
+- DNS resolver (uses simplelru) — :go-pkg{mod="darvaza.org/resolver"}
+- Structured logging — :go-pkg{mod="darvaza.org/slog"}

content/projects/darvaza-core.md

@@ -0,0 +1,17 @@
+---
+title: darvaza.org/core
+description: Fundamental helpers for Darvaza projects — type constraints, context utilities, error handling, and more.
+category:
+  - darvaza
+  - go
+repo: github:darvaza-proxy/core
+licence: MIT
+go: darvaza.org/core
+---
+
+Fundamental set of helpers used across Darvaza projects. Zero external
+dependencies — only Go's standard library is allowed.
+
+Covers type constraints, context utilities, network helpers, generic
+slice/map operations, error handling with compound errors, stack
+tracing, synchronisation primitives, and testing assertions.

content/projects/darvaza-resolver.md

@@ -0,0 +1,63 @@
+---
+title: darvaza.org/resolver
+description: Pluggable DNS resolver library with forwarding, iterative, and parallel lookup strategies built on miekg/dns.
+category:
+  - darvaza
+  - networking
+  - go
+repo: github:darvaza-proxy/resolver
+licence: MIT
+go: darvaza.org/resolver
+---
+
+Pluggable DNS resolver library built on :go-pkg{mod="github.com/miekg/dns" label="miekg/dns"}.
+Defines the :go-pkg{mod="darvaza.org/resolver" sym="Resolver" short},
+:go-pkg{mod="darvaza.org/resolver" sym="Lookuper" short},
+and :go-pkg{mod="darvaza.org/resolver" sym="Exchanger" short}
+interfaces that decouple DNS consumers from the transport and
+resolution strategy.
+
+Three resolver constructors cover the common cases:
+`SystemResolver` wraps :go-pkg{mod="net" sym="Resolver"},
+`NewResolver` delegates to any `Lookuper`,
+and `NewRootResolver` performs iterative resolution from the
+root servers.
+
+## Lookuper implementations
+
+| Lookuper | Description |
+|----------|-------------|
+| :go-pkg{mod="darvaza.org/resolver" sym="SingleLookuper" short} | Forwards queries to a single :go-pkg{mod="darvaza.org/resolver" dir="pkg/client" sym="Client" short} |
+| :go-pkg{mod="darvaza.org/resolver" sym="MultiLookuper" short} | Fans out to multiple lookupers, returns the first response |
+| :go-pkg{mod="darvaza.org/resolver" sym="RootLookuper" short} | Iterative resolution from root nameservers |
+| :go-pkg{mod="darvaza.org/resolver" sym="SingleFlight" short} | Deduplicates identical concurrent queries |
+
+Well-known recursive resolvers (Google, Cloudflare, Quad9) are
+available as one-liner constructors.
+
+## Client middleware
+
+| Middleware | Description |
+|------------|-------------|
+| :go-pkg{mod="darvaza.org/resolver" dir="pkg/client" sym="Auto" short} | Selects protocol by server prefix (`udp://`, `tcp://`, `tls://`), retries truncated UDP as TCP |
+| :go-pkg{mod="darvaza.org/resolver" dir="pkg/client" sym="SingleFlight" short} | Per-server deduplication with short-lived caching |
+| :go-pkg{mod="darvaza.org/resolver" dir="pkg/client" sym="WorkerPool" short} | Concurrency limiter for exchange calls |
+| :go-pkg{mod="darvaza.org/resolver" dir="pkg/client" sym="NoAAAA" short} | Strips `AAAA` records for IPv4-only environments |
+
+## Additional packages
+
+- The :go-pkg{dir="pkg/server" mod="darvaza.org/resolver"} package
+  provides a DNS server handler on top of any `Lookuper`
+  or `Exchanger`.
+- The :go-pkg{dir="pkg/reflect" mod="darvaza.org/resolver"} package
+  provides optional logging middleware
+  using :go-pkg{mod="darvaza.org/slog"}.
+- The :go-pkg{dir="pkg/errors" mod="darvaza.org/resolver"} package
+  provides standard :go-pkg{mod="net" sym="DNSError"} wrappers
+  with :go-pkg{mod="github.com/miekg/dns" sym="Msg"} conversion.
+
+## See also
+
+- Network helpers — :go-pkg{mod="darvaza.org/x/net"}
+- Structured logging — :go-pkg{mod="darvaza.org/slog"}
+- DNS library — :go-pkg{mod="github.com/miekg/dns" label="miekg/dns"}

content/projects/darvaza-slog.md

@@ -0,0 +1,37 @@
+---
+title: darvaza.org/slog
+description: Backend-agnostic structured logging interface with adapter handlers for popular Go loggers.
+category:
+  - darvaza
+  - go
+repo: github:darvaza-proxy/slog
+licence: MIT
+go: darvaza.org/slog
+---
+
+A backend-agnostic interface for structured logging. Libraries import
+`slog` to emit structured logs without forcing a specific backend on
+their users. Features method chaining (fluent API), six log levels,
+context integration, and immutable loggers safe for concurrent use.
+
+## Adapters
+
+Bidirectional adapters convert in both directions — use the external
+logger as an `slog` backend, or create an external logger backed by
+`slog`.
+
+| Handler | Module | Description |
+|---------|--------|-------------|
+| logr | :badge-version-go{mod="darvaza.org/slog/handlers/logr"} | Bidirectional adapter for :go-pkg{mod="github.com/go-logr/logr" label="go-logr/logr"} |
+| logrus | :badge-version-go{mod="darvaza.org/slog/handlers/logrus"} | Bidirectional adapter for :go-pkg{mod="github.com/sirupsen/logrus" label="sirupsen/Logrus"} |
+| zap | :badge-version-go{mod="darvaza.org/slog/handlers/zap"} | Bidirectional adapter for :go-pkg{mod="go.uber.org/zap" label="Uber's zap"} |
+| zerolog | :badge-version-go{mod="darvaza.org/slog/handlers/zerolog"} | Wraps :go-pkg{mod="github.com/rs/zerolog" label="rs/zerolog"} as an slog backend |
+
+## Utility handlers
+
+| Handler | Module | Description |
+|---------|--------|-------------|
+| cblog | :badge-version-go{mod="darvaza.org/slog/handlers/cblog"} | Channel-based handler for custom log processing |
+| filter | :badge-version-go{mod="darvaza.org/slog/handlers/filter"} | Middleware to filter and transform log entries |
+| discard | :badge-version-go{mod="darvaza.org/slog/handlers/discard"} | No-op handler for optional logging |
+| mock | :badge-version-go{mod="darvaza.org/slog" dir="handlers/mock"} | Records log entries for testing assertions |

content/projects/darvaza-x-cmp.md

@@ -0,0 +1,23 @@
+---
+title: darvaza.org/x/cmp
+description: Generic helpers to compare and match values.
+category:
+  - darvaza
+  - go
+repo: github:darvaza-proxy/x/cmp
+licence: MIT
+go: darvaza.org/x/cmp
+---
+
+Generic `CompFunc[T]` (three-way) and `CondFunc[T]` (boolean)
+types with conversion functions between the two styles — `AsLess`,
+`AsCmp`, `AsEqual`, `Reverse`. Works with any type via custom
+comparators, or directly
+with `comparable`/:go-pkg{mod="darvaza.org/core" sym="Ordered"}
+types.
+
+The composable `Matcher[T]` interface chains predicates with
+`And`, `Or`, and `Not`. Factory functions (`MatchEq`, `MatchLt`,
+`MatchGtEq`, …) produce matchers from values or comparators, and
+`Compose` transforms across types — e.g. match on a struct field
+without unwrapping manually.

content/projects/darvaza-x-config.md

@@ -0,0 +1,23 @@
+---
+title: darvaza.org/x/config
+description: Helpers for handling config structs — decoding, defaults, and validation.
+category:
+  - darvaza
+  - go
+repo: github:darvaza-proxy/x/config
+licence: MIT
+go: darvaza.org/x/config
+---
+
+Format-agnostic configuration loader. A generic `Loader[T]`
+tries candidate filenames in order, decodes via a user-supplied
+`Decoder` (TOML, YAML, JSON — any format works), applies struct-tag
+defaults, expands shell-style `${VAR}` variables, and validates
+the result with :go-pkg{mod="github.com/go-playground/validator/v10" label="go-playground/validator"}.
+
+Subpackage :go-pkg{mod="darvaza.org/x/config" dir="expand" label="config/expand"}
+provides :go-pkg{mod="mvdan.cc/sh/v3" label="mvdan.cc/sh"}-powered
+variable substitution from any source.
+Subpackage :go-pkg{mod="darvaza.org/x/config" dir="appdir" label="config/appdir"}
+handles XDG/FHS-aware directory discovery (`UserConfigDir`,
+`SysConfigDir`, `AllConfigDir`).

content/projects/darvaza-x-container.md

@@ -0,0 +1,23 @@
+---
+title: darvaza.org/x/container
+description: Generic data structure implementations extending Go's standard containers.
+category:
+  - darvaza
+  - go
+repo: github:darvaza-proxy/x/container
+licence: MIT
+go: darvaza.org/x/container
+---
+
+Three generic collection types. `container/list` wraps
+:go-pkg{mod="container/list" sym="List"} as a type-safe `List[T]`
+with match, filter, and move operations. `container/set` provides a hash-bucketed,
+thread-safe `Set[K,H,T]` keyed by user-supplied hash and match
+functions.
+
+`container/slices` implements sorted-slice-backed sets —
+`CustomSet[T]` for any type with a custom comparator, and
+`OrderedSet[T]` as a convenience for :go-pkg{mod="darvaza.org/core" sym="Ordered"}
+types. All
+sets support `Add`, `Remove`, `Contains`, `ForEach`, `Clone`,
+and capacity management (`Reserve`, `Grow`, `Trim`).

content/projects/darvaza-x-fs.md

@@ -0,0 +1,33 @@
+---
+title: darvaza.org/x/fs
+description: Helpers for working with fs.FS — globbing, extended interfaces, and file locking.
+category:
+  - darvaza
+  - go
+repo: github:darvaza-proxy/x/fs
+licence: MIT
+go: darvaza.org/x/fs
+---
+
+Shadow of Go's :go-pkg{mod="io/fs"} package that re-exports
+standard types and adds write-side interfaces mirroring
+:go-pkg{mod="os"} — `ChmodFS`, `ChtimesFS`, `MkdirFS`,
+`MkdirAllFS`, `MkdirTempFS`, `ReadlinkFS`, `RemoveFS`,
+`RemoveAllFS`, `RenameFS`, `SymlinkFS`, and `WriteFileFS`.
+
+File globbing compiles patterns
+via :go-pkg{mod="github.com/gobwas/glob" label="gobwas/glob"} with
+full `**` support for recursive matching. `Glob` walks
+an :go-pkg{mod="io/fs" sym="FS"} and returns all matches;
+`GlobCompile` and `Match` separate compilation from traversal
+for reuse. `Clean` and `Split` extend the standard path
+utilities with validity reporting.
+
+The :go-pkg{mod="darvaza.org/x/fs" dir="fssyscall"} sub-package
+provides cross-platform advisory file locking —
+`LockEx`, `UnlockEx`, and non-blocking `TryLockEx` — backed
+by `flock(2)` on Linux and `LockFileEx` on Windows. Convenience
+wrappers (`FLockEx`, `FUnlockEx`, `FTryLockEx`) accept
+an `*os.File` directly.
+The :go-pkg{mod="darvaza.org/x/fs" dir="flock"} sub-package wraps
+these into a single `LockEx(filename)` call.

content/projects/darvaza-x-net.md

@@ -0,0 +1,37 @@
+---
+title: darvaza.org/x/net
+description: Generic network helpers — port binding with retry, reconnecting TCP clients.
+category:
+  - darvaza
+  - networking
+  - go
+repo: github:darvaza-proxy/x/net
+licence: MIT
+go: darvaza.org/x/net
+---
+
+Network helpers extending Go's standard :go-pkg{mod="net"} package.
+Top-level utilities validate and split host/port pairs, and define
+a :go-pkg{mod="darvaza.org/x/net" sym="Dialer" short} interface
+compatible with `*net.Dialer`.
+
+The :go-pkg{mod="darvaza.org/x/net" dir="bind"} sub-package
+provides advanced port binding — multi-interface and multi-address
+listening, automatic port retry with configurable attempts,
+`SO_REUSEADDR`/`SO_REUSEPORT` control, and a context-aware
+`ListenConfig` that creates TCP listeners and UDP connections
+in bulk.
+
+The :go-pkg{mod="darvaza.org/x/net" dir="reconnect"} sub-package
+implements a generic reconnecting client for TCP and Unix domain
+sockets. Lifecycle callbacks (`OnConnect`, `OnSession`,
+`OnDisconnect`, `OnError`) drive application logic, while
+configurable backoff and context-based cancellation manage retries.
+A generic `StreamSession[Input, Output]` adds message-oriented
+I/O with pluggable codecs and stampede-safe send/receive channels.
+
+## See also
+
+- TLS certificate management — :go-pkg{mod="darvaza.org/x/tls"}
+- HTTP handler utilities — :go-pkg{mod="darvaza.org/x/web"}
+- DNS resolver library — :go-pkg{mod="darvaza.org/resolver"}

content/projects/darvaza-x-sync.md

@@ -0,0 +1,24 @@
+---
+title: darvaza.org/x/sync
+description: Synchronisation primitive interfaces with panic-safe cleanup.
+category:
+  - darvaza
+  - go
+repo: github:darvaza-proxy/x/sync
+licence: MIT
+go: darvaza.org/x/sync
+---
+
+Defines `Mutex`, `RWMutex`, and their context-aware variants as
+interfaces, with panic-safe wrappers (`SafeLock`, `SafeUnlock`, …)
+that recover panics
+via :go-pkg{mod="darvaza.org/core" func="Catch"} and aggregate
+errors. Multi-mutex operations acquire locks in order and
+reverse-unlock on failure.
+
+Higher-level primitives: `SpinLock` (atomic CAS), channel-based
+`Semaphore` (concurrent readers, exclusive writers), `Barrier` and
+`Count` condition variables,
+and :go-pkg{mod="darvaza.org/x/sync" dir="workgroup" sym="Group"} —
+a context-aware goroutine manager with cancellation propagation and
+panic recovery.