go-platform

README

go-platform

Shared Go libraries for jedi-knights services: structured errors, HTTP utilities, JWT helpers, and test utilities.

Table of contents

• Overview
• Packages
• Requirements
• Installation
• Usage
• Configuration
• Development
• Contributing
• License

Overview

go-platform is a single Go module holding shared utility packages used by multiple jedi-knights services. Each package is small, has a narrow purpose, and is designed to be imported independently. The module pairs with jedi-knights/go-logging for structured logging.

Packages

Package	Purpose	Status
apperrors	Structured AppError with ErrorCode and HTTP status mapping	✅ Available
jwtutil	Canonical Claims, Sign, Parse for HS256 JWTs	Planned
httputil	WriteJSON, WriteError, request and trace ID middleware	Planned (blocked on go-logging v2.0.0 tag)
testutil	Shared test helpers	Under review
audit	Agent audit event schema + pluggable sinks (see ADR-0018 in identity-platform-go)	✅ Available
audit/durable	Postgres-backed at-least-once durable sink (ADR-0019)	✅ Available
otel	Minimal OpenTelemetry bootstrap for end-to-end tracing	✅ Available

Requirements

• Go 1.26 or later

Installation

go get github.com/jedi-knights/go-platform@latest

Import individual packages:

import (
    "github.com/jedi-knights/go-platform/apperrors"
    "github.com/jedi-knights/go-platform/jwtutil"
    "github.com/jedi-knights/go-platform/httputil"
)

Usage

apperrors

import "github.com/jedi-knights/go-platform/apperrors"

err := apperrors.New(apperrors.ErrCodeNotFound, "user not found")
status := apperrors.HTTPStatus(err) // 404

See apperrors/ for the full reference.

Agentic posture roadmap

Two new packages are planned to support the portfolio-wide agentic-enterprise posture documented in jedi-knights/architecture/docs/agentic-posture.md:

• audit — structured agent-audit events with a stable cross-service schema (see ADR-0018 in identity-platform-go). Pluggable sinks (stderr JSON, OTel log, append-only file). Non-blocking emission so the audit hot path can't fail the underlying operation.
• otel — minimal OpenTelemetry bootstrap (span helpers, context propagation, env-based exporter selection) so every service emits traces with consistent agent_id, tool_name, policy_decision attributes.

Both packages release independently via the existing semantic-release pipeline. The jwtutil.Claims type is the entry point for the new actor_type / agent_id claims described in ADR-0015 of identity-platform-go — added additively, no breaking change.

Configuration

This module has no module-level configuration. Each package documents its own options where applicable.

Development

# Run tests with race detector
go test ./... -race -count=1

# Lint
golangci-lint run ./...

# Tidy and verify dependencies
go mod tidy && go mod verify

The repository uses Task — see Taskfile.yml for the canonical task list.

Contributing

Issues and pull requests welcome. Conventional Commits required (see CLAUDE.md for scopes).

License

MIT