block / block/proto-fleet

Retire collection.v1 wire contract + rename Go package to deviceset

Open
#255 0 comments 0 reactions 0 assignees View on GitHub
enhancement server
Dominant language
Go
Stars
55
Forks
16
Avg merge
1d 22h
Merged PRs (30d)
87

Description

**Parent:** #229
**Related PR:** #249 (shim landed; this follow-up retires the shim)

## Context

In #249 we introduced `device_set.v1` as the canonical wire contract for racks/groups but kept `collection.v1` as a deprecated alias so old clients keep working. The Go domain layer (package `collection`, struct `collection.Service`) was *not* renamed — only the wire proto changed.

This is a transitional state. The Go names disagree with both the new wire proto (`device_set.v1`) and the underlying DB schema (`device_set`, `device_set_membership`, `device_set_rack`). Retiring the wire shim is the natural moment to also align the Go names.

## Scope

One PR, because splitting rename and retirement leaves an awkward intermediate state where Go names disagree with both wire and DB.

1. **Delete `collection.v1` proto + generated stubs**
- `proto/collection/v1/*.proto`
- `server/generated/grpc/collection/v1/*`
- All `collection.v1` registrations in the server bootstrap
2. **Rename Go package: `domain/collection` → `domain/deviceset`**
- File path: `server/internal/domain/collection/*` → `server/internal/domain/deviceset/*`
3. **Rename types:**
- `collection.Service` → `deviceset.Service`
- `interfaces.CollectionStore` → `interfaces.DeviceSetStore` (+ regen mocks)
- `interfaces.CollectionListParams` etc. → `DeviceSet*`
4. **Drop the legacy proto wrapper:**
- Delete `Service.ListCollections(ctx, *pb.ListCollectionsRequest)` — the proto-shaped entry point
- `ListCollectionsDomain` becomes the only list entry point (probably renamed to just `List`)
5. **Drop the deprecated-zones shim in `convert.go`:**
- Remove the `Zones []string` → wildcard `ZoneKey` translation
- Remove `[deprecated = true]` field on `ListDeviceSetsRequest`
- The `zones` and legacy filter fields can be `reserved` in proto3

## Pre-flight checks

Worth verifying before kicking off the rename — these may expand scope:

- `device_set.v1.proto` still imports `collection/v1/...` for some shared types (rack info, member details, etc.). Those types either need to move to `device_set/v1` or be inlined first.
- The store's `ListCollections` signature uses `collectionpb.CollectionType` — that becomes `dspb.DeviceSetType`. Check downstream callers in stats/telemetry paths.
- Activity log event types may reference \"collection\" in strings — grep `activitymodels` for `collection` and decide whether to migrate stored event-type strings or leave them as historical labels.
- Confirm no external consumers (mobile, internal tools, dashboards) are still on `collection.v1` before deletion. Connect-RPC analytics or proxy logs should answer this.

## Out of scope

- Database table renames (`device_set` is already correctly named)
- Any frontend changes — FE was already migrated to `device_set.v1` types in #249

## Risk

Mechanical rename touches a lot of files but is low-risk because:
- Go compiler catches every missed import
- No semantic changes — pure rename + deletion
- Tests stay in place; only their import paths shift

The only real risk is the proto deletion — if any external client is still on `collection.v1`, it breaks. Pre-flight check above covers that.

Contributor guide

Open the contributing guide

Research direction

Start by checking device_set.v1.proto imports, the collection.v1 proto and generated stubs, and collection.v1 registrations in the server bootstrap. Then trace domain/collection, ListCollections callers, stats/telemetry paths, activitymodels, and external-consumer usage before committing to deletion. Done means the legacy proto and shims are gone, Go names and paths use deviceset, mocks regenerate, and the existing tests pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, grpc
Domain
api, backend
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.