Documentation
¶
Overview ¶
Package schema-level hooks live here.
Removed 2026-04-28 (post v1.18.5): otelMutationHook(typeName) created one OTel span per ent mutation. With sync cycles upserting up to ~270k objects (full catch-up after a long downtime / cursor reset), the resulting per-mutation spans inflated the parent sync trace to >7.5 MB and tripped Tempo's per-trace size cap (TRACE_TOO_LARGE).
Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
If a new per-Op tracing need arises, prefer wiring it at a coarser level (per-batch or per-chunk) than per-mutation.
Package schema defines the entgo schema types for PeeringDB objects.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ColumnEdges = map[string][]ColumnEdge{
"netixlan": {{TraversalKey: "ix_side", Column: "ix_side_id", TargetType: "fac"}},
}
ColumnEdges maps a PeeringDB type to its column edges. Consumed by cmd/pdb-compat-allowlist, which checks each entry against the ent graph and emits it into internal/pdbcompat/allowlist_gen.go Edges. A bad entry (unknown type, column that is not a nillable int with an index, or a clash with an existing edge) fails codegen.
Add an entry only where upstream queryable_relations exposes the FK (a model ForeignKey whose name xl does not rename, serializers.py: 403-441, :970-996). net_side is left out on purpose: xl renames it to network_side, which names no field, so upstream ignores its keys.
var PrepareQueryAllows = map[string]schemaannot.PrepareQueryAllowAnnotation{ "org": { Fields: []string{ "net__name", "net__asn", "ix__name", "fac__name", "fac__country", }, }, "net": { Fields: []string{ "org__name", "org__id", }, }, "fac": { Fields: []string{ "org__name", "campus__name", "ixlan__ix__fac_count", }, }, "ix": { Fields: []string{ "org__name", "ixpfx__prefix", }, }, "campus": { Fields: []string{ "org__name", "fac__name", "fac__country", }, }, "carrier": { Fields: []string{ "org__name", "fac__name", "fac__country", }, }, "ixlan": { Fields: []string{ "ix__name", "ix__id", "ixpfx__prefix", }, }, "ixpfx": { Fields: []string{ "ixlan__name", "ixlan__ix__name", "ixlan__ix__id", }, }, "ixfac": { Fields: []string{ "fac__name", "fac__country", "fac__city", "ix__name", }, }, "netfac": { Fields: []string{ "net__name", "net__asn", "fac__name", "fac__country", }, }, "netixlan": { Fields: []string{ "net__name", "net__asn", "ixlan__name", }, }, "carrierfac": { Fields: []string{ "carrier__name", "fac__name", "fac__country", }, }, "poc": { Fields: []string{ "net__name", "net__asn", }, }, }
PrepareQueryAllows is the hand-written source-of-truth for the Path A traversal allowlists. Each entry is derived from the upstream peeringdb_server/serializers.py prepare_query of the type (its get_relation_filters seed list), or from related_fields / queryable_relations when the serializer has no such list. The keys are the mirror's choice of PDB-surface aliases, not a copy of an upstream list: some resolve keys that upstream ignores, and some cannot resolve here (see the per-entry notes and docs/API.md § Known Divergences).
Line numbers cite PeeringDB 2.83.0 (465931c0).
Consumed by cmd/pdb-compat-allowlist at codegen time to emit internal/pdbcompat/allowlist_gen.go. Keys are PeeringDB type strings ("net", "fac", etc. — the Registry/URL namespace), matching the map keys emitted in the generated file.
Keys use TraversalKey tokens (equivalent to PeeringDB type names like "netfac", "netixlan") — NOT the ent edge Go names ("network_facilities", "network_ix_lans"). The runtime parser resolves entries via LookupEdge, which indexes Edges[] by TraversalKey; a Go-name key would be silently ignored.
Living in this sibling file (rather than inside Annotations() on the per-entity generated ent/schema/{type}.go) keeps the source-of-truth safe from cmd/pdb-schema-generate, which regenerates {type}.go from schema/peeringdb.json and would otherwise strip these hand-authored annotations on every full-tree `go generate ./...`. See ent/schema/poc_policy.go for the original sibling-file precedent.
When adding a new allowlist entry, cite the upstream serializers.py line it derives from — the citations are load-bearing for future audits against upstream revisions.
Functions ¶
This section is empty.
Types ¶
type Campus ¶
Campus holds the schema definition for the Campus entity. Maps to the PeeringDB "campus" object type.
func (Campus) Annotations ¶
func (Campus) Annotations() []schema.Annotation
Annotations of the Campus.
func (Campus) Hooks ¶
Hooks returns Campus mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
type Carrier ¶
Carrier holds the schema definition for the Carrier entity. Maps to the PeeringDB "carrier" object type.
func (Carrier) Annotations ¶
func (Carrier) Annotations() []schema.Annotation
Annotations of the Carrier.
func (Carrier) Hooks ¶
Hooks returns Carrier mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
type CarrierFacility ¶
CarrierFacility holds the schema definition for the CarrierFacility entity. Maps to the PeeringDB "carrierfac" object type.
func (CarrierFacility) Annotations ¶
func (CarrierFacility) Annotations() []schema.Annotation
Annotations of the CarrierFacility.
func (CarrierFacility) Edges ¶
func (CarrierFacility) Edges() []ent.Edge
Edges of the CarrierFacility.
func (CarrierFacility) Fields ¶
func (CarrierFacility) Fields() []ent.Field
Fields of the CarrierFacility.
func (CarrierFacility) Hooks ¶
func (CarrierFacility) Hooks() []ent.Hook
Hooks returns CarrierFacility mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
func (CarrierFacility) Indexes ¶
func (CarrierFacility) Indexes() []ent.Index
Indexes of the CarrierFacility.
type ColumnEdge ¶ added in v1.37.0
type ColumnEdge struct {
// TraversalKey is the first key segment, in upstream spelling.
TraversalKey string
// Column is the FK column on the table of the declaring type.
Column string
// TargetType is the PeeringDB type of the referenced rows.
TargetType string
}
ColumnEdge declares a forward traversal edge that pdbcompat resolves over a nullable FK column that has no ent edge. Path B walks it like an ent edge: <TraversalKey>__<field> filters the rows of TargetType whose id is in Column. The edge exists only in the pdbcompat Edges map. It adds no FK constraint and nothing to the ent client, REST, GraphQL or ConnectRPC.
type Facility ¶
Facility holds the schema definition for the Facility entity. Maps to the PeeringDB "fac" object type.
func (Facility) Annotations ¶
func (Facility) Annotations() []schema.Annotation
Annotations of the Facility.
func (Facility) Hooks ¶
Hooks returns Facility mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
type InternetExchange ¶
InternetExchange holds the schema definition for the InternetExchange entity. Maps to the PeeringDB "ix" object type.
func (InternetExchange) Annotations ¶
func (InternetExchange) Annotations() []schema.Annotation
Annotations of the InternetExchange.
func (InternetExchange) Edges ¶
func (InternetExchange) Edges() []ent.Edge
Edges of the InternetExchange.
func (InternetExchange) Fields ¶
func (InternetExchange) Fields() []ent.Field
Fields of the InternetExchange.
func (InternetExchange) Hooks ¶
func (InternetExchange) Hooks() []ent.Hook
Hooks returns InternetExchange mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
func (InternetExchange) Indexes ¶
func (InternetExchange) Indexes() []ent.Index
Indexes of the InternetExchange.
func (InternetExchange) Mixin ¶ added in v1.17.0
func (InternetExchange) Mixin() []ent.Mixin
Mixin wires the diacritic-fold shadow columns onto InternetExchange. Sibling-file pattern — see network_fold.go for the rationale.
type IxFacility ¶
IxFacility holds the schema definition for the IxFacility entity. Maps to the PeeringDB "ixfac" object type.
func (IxFacility) Annotations ¶
func (IxFacility) Annotations() []schema.Annotation
Annotations of the IxFacility.
func (IxFacility) Hooks ¶
func (IxFacility) Hooks() []ent.Hook
Hooks returns IxFacility mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
type IxLan ¶
IxLan holds the schema definition for the IxLan entity. Maps to the PeeringDB "ixlan" object type.
func (IxLan) Hooks ¶
Hooks returns IxLan mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
type IxPrefix ¶
IxPrefix holds the schema definition for the IxPrefix entity. Maps to the PeeringDB "ixpfx" object type.
func (IxPrefix) Annotations ¶
func (IxPrefix) Annotations() []schema.Annotation
Annotations of the IxPrefix.
func (IxPrefix) Hooks ¶
Hooks returns IxPrefix mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
type Network ¶
Network holds the schema definition for the Network entity. Maps to the PeeringDB "net" object type.
func (Network) Annotations ¶
func (Network) Annotations() []schema.Annotation
Annotations of the Network.
func (Network) Hooks ¶
Hooks returns Network mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
func (Network) Mixin ¶ added in v1.17.0
Mixin wires the diacritic-fold shadow columns onto Network. Lives in this sibling file because network.go is regenerated by cmd/pdb-schema-generate from schema/peeringdb.json; the generator only touches files named after the model type (network.go) so this file is invisible to it. ent's codegen discovers the method via reflection on the Network schema type, so the file split is transparent to ent.
type NetworkFacility ¶
NetworkFacility holds the schema definition for the NetworkFacility entity. Maps to the PeeringDB "netfac" object type.
func (NetworkFacility) Annotations ¶
func (NetworkFacility) Annotations() []schema.Annotation
Annotations of the NetworkFacility.
func (NetworkFacility) Edges ¶
func (NetworkFacility) Edges() []ent.Edge
Edges of the NetworkFacility.
func (NetworkFacility) Fields ¶
func (NetworkFacility) Fields() []ent.Field
Fields of the NetworkFacility.
func (NetworkFacility) Hooks ¶
func (NetworkFacility) Hooks() []ent.Hook
Hooks returns NetworkFacility mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
func (NetworkFacility) Indexes ¶
func (NetworkFacility) Indexes() []ent.Index
Indexes of the NetworkFacility.
type NetworkIxLan ¶
NetworkIxLan holds the schema definition for the NetworkIxLan entity. Maps to the PeeringDB "netixlan" object type.
func (NetworkIxLan) Annotations ¶
func (NetworkIxLan) Annotations() []schema.Annotation
Annotations of the NetworkIxLan.
func (NetworkIxLan) Hooks ¶
func (NetworkIxLan) Hooks() []ent.Hook
Hooks returns NetworkIxLan mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
func (NetworkIxLan) Indexes ¶
func (NetworkIxLan) Indexes() []ent.Index
Indexes of the NetworkIxLan.
type Organization ¶
Organization holds the schema definition for the Organization entity. Maps to the PeeringDB "org" object type.
func (Organization) Annotations ¶
func (Organization) Annotations() []schema.Annotation
Annotations of the Organization.
func (Organization) Hooks ¶
func (Organization) Hooks() []ent.Hook
Hooks returns Organization mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
func (Organization) Indexes ¶
func (Organization) Indexes() []ent.Index
Indexes of the Organization.
func (Organization) Mixin ¶ added in v1.17.0
func (Organization) Mixin() []ent.Mixin
Mixin wires the diacritic-fold shadow columns onto Organization. Sibling-file pattern — see network_fold.go for the rationale.
type Poc ¶
Poc holds the schema definition for the Poc entity. Maps to the PeeringDB "poc" object type.
func (Poc) Hooks ¶
Hooks returns Poc mutation hooks. Removed 2026-04-28 (post v1.18.5): the prior otelMutationHook created one OTel span per mutation, which exploded the parent sync trace to >7.5MB during large catch-up cycles (270k upserts → 270k child spans → Tempo rejected the trace with TRACE_TOO_LARGE). Per-type and per-cycle observability is already covered by:
- pdbplus.sync.type.objects counter (per-type cumulative)
- pdbplus.sync.duration histogram (per-cycle)
- sync-fetch-{type} / sync-upsert-{type} per-step spans
Restore on a per-Op basis only if a specific debugging need surfaces.
func (Poc) Policy ¶ added in v1.14.0
Policy returns the privacy policy for the Poc entity.
Lives in this separate file because `poc.go` is regenerated by `cmd/pdb-schema-generate` from `schema/peeringdb.json`, which would strip hand-added methods. The generator only touches files named after the generated type (`poc.go`), so `poc_policy.go` is invisible to it. ent's codegen still picks this method up via reflection on the Poc schema type — the Go file split is transparent to ent.
Query rule: a row is admitted when its visible value is in privctx.TierFrom(ctx).AdmittedVisibilities(), or when it is NULL (see the NULL-safety note below). TierPublic sees Public rows. TierUsers (env-override PDBPLUS_PUBLIC_TIER=users, or a future OAuth session) sees Public and Users rows. No tier sees Private rows: upstream shows them only to members of the owning organization (2.83.0 permissions.py:336-339, signals.py:343-347), and the mirror has no organization membership. Sync workers bypass the policy via privacy.DecisionContext(ctx, privacy.Allow) set at worker entry (internal/sync/worker.go), so ingest is unaffected.
No Mutation rule: sync writes travel the bypass; no other writers exist on this read-only mirror.
NULL-safety: SQL three-valued logic makes `visible = 'Public'` FALSE for NULL, so we OR with VisibleIsNil for defence-in-depth against any future migration that leaves rows with unset visibility. The schema's Default("Public") also backstops this on inserts — two independent safeguards.
Source Files
¶
- campus.go
- campus_annotations.go
- campus_fold.go
- carrier.go
- carrier_fold.go
- carrierfacility.go
- facility.go
- facility_fold.go
- fold_mixin.go
- hooks.go
- internetexchange.go
- internetexchange_fold.go
- ixfacility.go
- ixlan.go
- ixprefix.go
- network.go
- network_fold.go
- networkfacility.go
- networkixlan.go
- organization.go
- organization_fold.go
- pdb_allowlists.go
- poc.go
- poc_policy.go
- types.go