Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/integration-candidate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,10 @@ jobs:
run: |
go build -o /dev/null ./cmd/crux
(cd crux && GOWORK=off go build -o /dev/null ./cmd/crux)
- name: Durable Crux lane and Hive participant integration
run: |
(cd crux && GOWORK=off go test -race -timeout 3m ./lanes ./api ./serve)
GOWORK=off go test -race -timeout 3m ./pkg/laneparticipant
- name: Crux module smoke (crux serve over a unix socket)
working-directory: src/crux
run: GOWORK=off bash scripts/smoke.sh
Expand Down
4 changes: 4 additions & 0 deletions .github/workflows/integration-technical-v2-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,10 @@ jobs:
run: |
go build -o /dev/null ./cmd/crux
(cd crux && GOWORK=off go build -o /dev/null ./cmd/crux)
- name: Durable Crux lane and Hive participant integration
run: |
(cd crux && GOWORK=off go test -race -timeout 3m ./lanes ./api ./serve)
GOWORK=off go test -race -timeout 3m ./pkg/laneparticipant
- name: Crux module smoke (crux serve over a unix socket)
working-directory: src/crux
run: GOWORK=off bash scripts/smoke.sh
Expand Down
8 changes: 8 additions & 0 deletions .github/workflows/v2-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,14 @@ jobs:
go build -o /dev/null ./cmd/crux
(cd crux && GOWORK=off go build -o /dev/null ./cmd/crux)

# Real embedded JetStream only: no live broker, cluster or deployment.
# Keep the standalone module boundary honest as well as the Hive adapter.
# Normal v2-tests shards also collect coverage for these packages.
- name: Durable Crux lane and Hive participant integration
run: |
(cd crux && GOWORK=off go test -race -timeout 3m ./lanes ./api ./serve)
GOWORK=off go test -race -timeout 3m ./pkg/laneparticipant

# crux/scripts/smoke.sh (`make -C crux smoke` locally; the self-hosted
# runners have no make) starts `crux serve` on a private unix socket
# with an empty runtime, drives it with `crux --server … ps` and GET
Expand Down
1,184 changes: 1,079 additions & 105 deletions NOTICE

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions changelog.d/added-crux-durable-lanes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Add opt-in, forge-neutral Crux durable event/work lanes backed by NATS JetStream, project-scoped API credentials, verified publish generations, replay, fenced leases, authorized audited expiration recovery, persistent fair retry rotation and reusable reserved delivery slots, with Hive participating through a read-only governor adapter.
1 change: 1 addition & 0 deletions changelog.d/fixed-crux-lane-diagnostics.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Distinguish durable lane broker initialization conflicts from unavailability without exposing backend details, and expose stable lane error-code constants while preserving existing HTTP responses.
58 changes: 58 additions & 0 deletions src/cmd/hive/lanes.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
package main

import (
"context"
"errors"
"os"
"strings"

"github.com/hivecommons/hive/crux/api"
"github.com/hivecommons/hive/pkg/governor"
"github.com/hivecommons/hive/pkg/laneparticipant"
)

// HIVE_LANES_ADDRESS is the opt-in gate. No broker or forge permissions are
// inferred from being Hive; its token is an ordinary configured Crux principal.
func (b *boot) installLaneParticipant() {
address := os.Getenv("HIVE_LANES_ADDRESS")
if address == "" {
return
}
lane, group, token := os.Getenv("HIVE_LANES_LANE"), os.Getenv("HIVE_LANES_GROUP"), os.Getenv("HIVE_LANES_TOKEN")
if lane == "" || group == "" || token == "" {
b.logger.Error("Hive lane participant disabled: incomplete configuration")
return
}
client, err := api.NewClient(address, token)
if err != nil {
b.logger.Error("Hive lane participant disabled: invalid Crux address")
return
}
participant, err := laneparticipant.New(client, lane, group, b.logger)
if err != nil {
b.logger.Error("Hive lane participant disabled: invalid configuration")
return
}
// Snapshot work is optional and read-only. No configured publisher means
// no registered handler, not a wildcard grant.
if publishers := os.Getenv("HIVE_LANES_SNAPSHOT_PROJECTS"); publishers != "" {
if err := participant.RegisterSnapshot(strings.Split(publishers, ","), b.gov.GetState); err != nil {
b.logger.Error("Hive lane participant disabled: invalid snapshot publisher configuration")
return
}
}
ctx := b.ctx
if ctx == nil {
ctx = context.Background()
}
laneCtx, cancel := context.WithCancel(ctx)
b.cleanup.push(cancel)
// Keep the existing hook observer; durable publication is an additional
// post-commit observer, not a replacement for local hooks.
b.gov.AddModeChangeObserver(func(change governor.ModeChange) { participant.ObserveMode(laneCtx, change) })
go func() {
if err := participant.Run(laneCtx); err != nil && !errors.Is(err, context.Canceled) {
b.logger.Error("Hive lane participant stopped", "error", err)
}
}()
}
1 change: 1 addition & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -3932,6 +3932,7 @@ func (b *boot) bootWatchersWith(deps bootWatchersDeps) {
// firing, so a later config reload that arms or disarms hooks is picked up
// without re-registering.
installGovernorModeChangeEmitter(b.gov)
b.installLaneParticipant()
installAgentPauseEmitter(b.agentMgr)

// Register custom GHE hostnames with the proxy allowlist so mode
Expand Down
3 changes: 3 additions & 0 deletions src/crux/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ and depends on nothing else in the Hive repository.
The design, the boundary rules and the roadmap are in
[`src/docs/design/crux.md`](../docs/design/crux.md); the operator pages are
[`crux-cli.md`](../docs/crux-cli.md) and [`crux-serve.md`](../docs/crux-serve.md).
Forge-neutral durable event/work lanes are described in
[`crux-lanes.md`](../docs/crux-lanes.md).

## What is in the module

Expand All @@ -22,6 +24,7 @@ The design, the boundary rules and the roadmap are in
| `crux/cli` | the `crux` command: `run`, `ps`, `logs`, `kick`, `stop`, `serve`, `agy-turn` (the pane-side agy subprocess), and `--server` remote mode |
| `crux/api`, `crux/serve` | the wire contract of `crux serve` (stdlib-only client and types, `api.RuntimeRoutes`: every `crux.Runtime` method → route) and the server |
| `crux/api/client` | `client.Runtime`: `crux.Runtime` over the API; what `crux/runtime.New` returns for `CRUX_MODE=sidecar` |
| `crux/lanes` | opt-in JetStream durable lanes: neutral project ACLs, event replay, claimable delivery groups and fenced receipts; Hive is an ordinary participant |
| `crux/api/callback`, `crux/hivecap` | the hive callback contract (capabilities hive serves the runtime: scoped tokens, agent mint, Bob credential, PRs, Linear, scanners, conditions, host policy, inference routes, effects, usage) and the runtime-side adapters `crux serve --hive-callback` installs; `api.HostSetters` is the table that accounts for every `crux.Host` setter (route / callback / config key / in-process-only) |
| `crux/runtime` | `runtime.New` (mode selection: `CRUX_MODE=inprocess` default, `sidecar`) and `runtime.Supervisor`, the child supervisor hive uses for `crux serve` when `CRUX_SUPERVISE=child` |
| `crux/defs` | the file-based agent-definition loader the module's binary uses |
Expand Down
2 changes: 1 addition & 1 deletion src/crux/api/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -279,7 +279,7 @@ func (c *Client) do(ctx context.Context, method, path string, in, out any) error
if err := checkStatus(resp); err != nil {
return err
}
if out == nil {
if out == nil || resp.StatusCode == http.StatusNoContent {
return nil
}
if err := json.NewDecoder(resp.Body).Decode(out); err != nil {
Expand Down
134 changes: 134 additions & 0 deletions src/crux/api/lanes.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
package api

import "time"

const PathLanes = "/" + Version + "/lanes"

// Lane error codes retain the same meaning across HTTP handlers and clients.
const (
CodeLaneUnavailable = "lane_unavailable"
CodeLaneForbidden = "lane_forbidden"
CodeLaneInvalid = "lane_invalid"
CodeLaneConflict = "lane_conflict"
CodeLaneCursor = "lane_cursor"
CodeLaneStale = "lane_stale"
CodeLaneCapacity = "lane_capacity"
CodeLaneTimeout = "lane_timeout"
CodeLaneCanceled = "lane_canceled"
)

// Lane IDs are plain subject-safe identifiers, not forge coordinates.
type Lane struct {
ID string `json:"id"`
Owner string `json:"owner"`
Publishers []string `json:"publishers"`
Subscribers []string `json:"subscribers"`
Groups map[string][]string `json:"groups"`
Recoverers map[string][]string `json:"recoverers,omitempty"`
}

const (
LaneEvent = "event"
LaneWork = "work"
)

// LanePublish deliberately has no caller-supplied publisher. Authentication
// supplies the project identity; provenance is optional, untrusted metadata.
type LanePublish struct {
ID string `json:"id"`
Kind string `json:"kind"`
Schema string `json:"schema"`
Provenance string `json:"provenance,omitempty"`
Payload []byte `json:"payload"`
}

type LaneEnvelope struct {
LanePublish
Lane string `json:"lane"`
Project string `json:"project"`
CreatedAt time.Time `json:"created_at"`
}

type LanePublished struct {
Sequence uint64 `json:"sequence"`
Duplicate bool `json:"duplicate"`
}

// A cursor is the last examined lane stream sequence, including work records
// skipped by event replay. Zero explicitly opts into the earliest retained data.
type LaneReplay struct {
Events []LaneRecord `json:"events"`
Cursor uint64 `json:"cursor"`
}

type LaneRecord struct {
Sequence uint64 `json:"sequence"`
Envelope LaneEnvelope `json:"envelope"`
}

type LaneClaim struct {
LaneRecord
Receipt string `json:"receipt"`
Expires time.Time `json:"expires"`
Attempt uint64 `json:"attempt"`
}

type LaneReceipt struct {
Sequence uint64 `json:"sequence"`
Receipt string `json:"receipt"`
}

type LaneRenewed struct {
Expires time.Time `json:"expires"`
}

type LaneGroupState struct {
Revision uint64 `json:"revision"`
Cursor uint64 `json:"cursor"`
FirstRetained uint64 `json:"first_retained"`
LastSequence uint64 `json:"last_sequence"`
Recoverable []LaneReceipt `json:"recoverable"`
Recoveries []LaneRecovered `json:"recoveries"`
Retries []LaneRetry `json:"retries"`
MissingThrough uint64 `json:"missing_through"`
Missing []LaneExpiration `json:"missing"`
Slots int `json:"slots"`
}

// LaneExpiration describes missing, lease-expired work without exposing its
// ownership receipt or representing successful execution.
type LaneExpiration struct {
Sequence uint64 `json:"sequence"`
Project string `json:"project"`
Attempt uint64 `json:"attempt"`
}

type LaneRetry struct {
Sequence uint64 `json:"sequence"`
Attempt uint64 `json:"attempt"`
AvailableAt time.Time `json:"available_at"`
}

// Recovery explicitly accepts an expired prefix and listed missing deliveries.
// Missing needs the configured group recovery capability, not a foreign receipt.
// Expired optionally supplies the caller's original receipts for extra fencing.
// Revision fences the entire delivery-group state.
type LaneRecover struct {
ID string `json:"id"`
Revision uint64 `json:"revision"`
CursorThrough uint64 `json:"cursor_through"`
Expired []LaneReceipt `json:"expired"`
Missing []uint64 `json:"missing"`
}

type LaneRecovered struct {
ID string `json:"id"`
Project string `json:"project"`
Cursor uint64 `json:"cursor"`
GapFrom uint64 `json:"gap_from,omitempty"`
GapThrough uint64 `json:"gap_through,omitempty"`
MissingThrough uint64 `json:"missing_through"`
Retired []uint64 `json:"retired"`
Expirations []LaneExpiration `json:"expirations"`
RecoveredAt time.Time `json:"recovered_at"`
}
59 changes: 59 additions & 0 deletions src/crux/api/lanes_client.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
package api

import (
"context"
"fmt"
"net/http"
"net/url"
)

func lanePath(lane string) string { return PathLanes + "/" + url.PathEscape(lane) }
func laneGroupPath(lane, group string) string {
return lanePath(lane) + "/groups/" + url.PathEscape(group)
}

func (c *Client) LaneRegistry(ctx context.Context) ([]Lane, error) {
var out []Lane
err := c.Do(ctx, http.MethodGet, PathLanes, nil, &out)
return out, err
}
func (c *Client) PublishLane(ctx context.Context, lane string, in LanePublish) (LanePublished, error) {
var out LanePublished
err := c.Do(ctx, http.MethodPost, lanePath(lane)+"/publish", in, &out)
return out, err
}
func (c *Client) ReplayLane(ctx context.Context, lane string, cursor uint64, limit int) (LaneReplay, error) {
var out LaneReplay
err := c.Do(ctx, http.MethodGet, lanePath(lane)+fmt.Sprintf("/events?cursor=%d&limit=%d", cursor, limit), nil, &out)
return out, err
}

// ClaimLane returns nil, nil when no work is currently claimable (HTTP 204).
func (c *Client) ClaimLane(ctx context.Context, lane, group string) (*LaneClaim, error) {
var out *LaneClaim
err := c.Do(ctx, http.MethodPost, laneGroupPath(lane, group)+"/claim", nil, &out)
return out, err
}
func (c *Client) AckLane(ctx context.Context, lane, group string, in LaneReceipt) error {
return c.Do(ctx, http.MethodPost, laneGroupPath(lane, group)+"/ack", in, nil)
}
func (c *Client) NackLane(ctx context.Context, lane, group string, in LaneReceipt) error {
return c.Do(ctx, http.MethodPost, laneGroupPath(lane, group)+"/nack", in, nil)
}
func (c *Client) RenewLane(ctx context.Context, lane, group string, in LaneReceipt) (LaneRenewed, error) {
var out LaneRenewed
err := c.Do(ctx, http.MethodPost, laneGroupPath(lane, group)+"/renew", in, &out)
return out, err
}

func (c *Client) InspectLaneGroup(ctx context.Context, lane, group string) (LaneGroupState, error) {
var out LaneGroupState
err := c.Do(ctx, http.MethodGet, laneGroupPath(lane, group), nil, &out)
return out, err
}

func (c *Client) RecoverLaneGroup(ctx context.Context, lane, group string, in LaneRecover) (LaneRecovered, error) {
var out LaneRecovered
err := c.Do(ctx, http.MethodPost, laneGroupPath(lane, group)+"/recover", in, &out)
return out, err
}
26 changes: 26 additions & 0 deletions src/crux/api/lanes_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
package api

import "testing"

func TestLaneErrorCodesPreserveWireValues(t *testing.T) {
for _, test := range []struct {
code string
wire string
}{
{CodeLaneUnavailable, "lane_unavailable"},
{CodeLaneForbidden, "lane_forbidden"},
{CodeLaneInvalid, "lane_invalid"},
{CodeLaneConflict, "lane_conflict"},
{CodeLaneCursor, "lane_cursor"},
{CodeLaneStale, "lane_stale"},
{CodeLaneCapacity, "lane_capacity"},
{CodeLaneTimeout, "lane_timeout"},
{CodeLaneCanceled, "lane_canceled"},
} {
t.Run(test.wire, func(t *testing.T) {
if test.code != test.wire {
t.Fatalf("code = %q, want %q", test.code, test.wire)
}
})
}
}
Loading
Loading