providerdata

type AppStoreCache ¶ added in v1.5.0

type AppStoreCache struct {
	// contains filtered or unexported fields
}

AppStoreCache holds the App Store listings one configured provider instance has looked up.

A listing cannot change within one plan in any way the plan could use, and a configuration that looks up the same app twice (once per target, or from two modules) should pay one request. Two outcomes are stored: a listing, and a definitive miss (*appstore.NotFoundError or *appstore.StorefrontMismatchError), because Apple answers both with a 200 and asking again returns the same answer. A transport or status failure is not stored, so the next caller retries it, the same rule this package applies to the Jamf Pro version fetch.

The map lock is never held across a request: concurrent callers for one query collapse onto a per-key sync.Once, as in aischemas.Cache, while callers for different queries proceed independently up to AppStoreMaxConcurrent.

func NewAppStoreCache(client *appstore.Client) *AppStoreCache

func (c *AppStoreCache) Lookup(ctx context.Context, q appstore.Query) (*appstore.App, error)

type AppTitleCatalogCache ¶

type AppTitleCatalogCache struct {
	// contains filtered or unexported fields
}

AppTitleCatalogCache holds one snapshot of the tenant's Jamf App Catalog title list per configured provider instance, read on first use.

The catalog is tenant-global and identical for every App Installer in a configuration, and each deployment needs it in both directions — a configured app_title_name resolved to a catalog id at plan time and again on apply, and the stored app_title_id reverse-resolved to its display name on every refresh. Without this a configuration with N App Installers pays 2N catalog requests on every plan on top of the N deployment reads, tripling the request count of a no-op plan. One unfiltered list answers all of it: the catalog is a few hundred titles and the SDK's list call pages at 2000, so the whole of it arrives in one round-trip.

A failed read is not cached: the next caller retries it. A transient blip or a momentary privilege problem on the first deployment must not blank every later deployment's app_title_name for the rest of the run — the same rule this package applies to the Jamf Pro version fetch and to the patch source catalogues.

The read itself is injected rather than written here. The SDK call it makes belongs to the App Installer package: that package declares the privileges it requires, and its tests derive that declaration from the call sites in its own files.

func ConfigureAppTitleCatalog(providerData any, read func(context.Context, *pro.Client) ([]pro.AppTitle, error)) *AppTitleCatalogCache

func (c *AppTitleCatalogCache) Titles(ctx context.Context) ([]pro.AppTitle, error)

type BenchmarkLock ¶ added in v1.6.0

type BenchmarkLock struct {
	// contains filtered or unexported fields
}

BenchmarkLock serializes compliance benchmark creates and deletes within one configured provider instance.

A benchmark is not one object: Jamf deploys it to Jamf Pro as about sixty (configuration profiles, policies, smart groups, extension attributes and scripts) and tears them down asynchronously after the delete is accepted. Wire-observed on the EU gateway 2026-10-18, deleting several benchmarks at once leaves some of those objects behind (two to eleven configuration profiles and policies per run) while every benchmark still reports a clean delete, and the same deletes run one at a time leave nothing. Terraform runs independent resources concurrently, so the resource holds this lock from the write until the benchmark has finished syncing or disappeared.

It is a one-slot channel rather than a sync.Mutex so a caller waiting for it still honours cancellation and its timeout. It serializes one provider process only: two `terraform apply` runs against the same environment can still overlap.

func (l *BenchmarkLock) Acquire(ctx context.Context) (func(), error)

type Data ¶

type Data struct {
	Client *jamfplatform.Client
	// contains filtered or unexported fields
}

Data is the value passed via ResourceData/DataSourceData/ListResourceData/ActionData. It bundles the authenticated SDK client with lazy Jamf Pro version state shared across all Pro resource Configure calls in a single terraform invocation.

Caching semantics:

• Successful version fetches are cached for the lifetime of the Data value.
• Errors are NOT cached — subsequent Configure calls will retry the fetch. This avoids a transient network/auth blip in the first Pro Configure poisoning every later Configure on the same terraform invocation.
• The provider-floor advisory warning is emitted at most once per Data value to prevent N duplicate warnings in configs that use N Pro resources.
• Once the floor advisory has been considered (emitted or determined not to be applicable), further Configure calls with empty minVer skip the version fetch entirely — there is nothing left to check on those code paths.

It also carries the API integration scope (environment, tenant, or organization) the provider was configured with, fixed before any construct runs and read via RequireScope; see scope.go.

func New(client *jamfplatform.Client) *Data

func (d *Data) AISchemaCache() *aischemas.Cache

func (d *Data) AppStoreCache() *AppStoreCache

func (d *Data) BenchmarkLock() *BenchmarkLock

func (d *Data) CollisionChecker() *collision.Checker

func (d *Data) EnableImpactAlerts()

func (d *Data) EnableNameCollisionCheck(cfg collision.Config)

func (d *Data) EnrollmentWriteLock() *sync.Mutex

func (d *Data) FiredOnce(key string) bool

func (d *Data) GetJamfProVersion(ctx context.Context) (string, error)

func (d *Data) ImpactCache() *impact.Cache

func (d *Data) RequireScope(resourceType string, allowed ...ScopeKind) diag.Diagnostics

func (d *Data) Scope() ScopeKind

func (d *Data) SetAppStoreClient(client *appstore.Client)

type PatchSourceCache ¶

type PatchSourceCache struct {
	// contains filtered or unexported fields
}

PatchSourceCache holds one PatchSourceCatalogues snapshot per configured provider instance, read on first use.

Both catalogues are tenant-global and identical for every patch software title in a configuration, and every title read outside the managed-resource steady state needs them, so without this a configuration with N patch software title data sources pays 2N identical catalogue requests on every plan and again on every apply.

A failed read is not cached: the next caller retries it. A transient blip or a momentary privilege problem on the first title must not blank every later title's source_id for the rest of the run — the same rule this package applies to the Jamf Pro version fetch and aischemas to its vendor schemas.

The read itself is injected rather than written here. The two SDK calls it makes belong to the patch software title package: that package declares the privileges they require, and its tests derive that declaration from the call sites in its own files.

func ConfigurePatchSources(providerData any, read func(context.Context, *proclassic.Client) (PatchSourceCatalogues, error)) *PatchSourceCache

func (c *PatchSourceCache) Catalogues(ctx context.Context) (PatchSourceCatalogues, error)

type PatchSourceCatalogues ¶

type PatchSourceCatalogues struct {
	Internal []proclassic.IDName
	External []proclassic.IDName
}

PatchSourceCatalogues is a snapshot of the tenant's two Jamf Pro patch source catalogues, internal and external, as one value.

It carries the catalogue entries as read rather than a name → id index, because the question its consumer asks is not a plain lookup: a patch software title names its source but never numbers it, a name present in both catalogues cannot be resolved at all, and the refusal has to name the candidate ids. Keeping the snapshot as-read leaves that decision in one pure function over these two slices (in the patch software title package, which owns the law and the calls that fill this), so the cache only ever answers "what does this tenant have", never "which id is it".

type ScopeKind ¶

type ScopeKind int

ScopeKind is the request context a Jamf API integration is bound to.

The three kinds are the three choices Jamf offers when an integration is created — *Organization management*, *Platform environment*, and *Tenant*. The gateway resolves which one applies from a request header (`X-Environment-Id` or `X-Tenant-Id`, stamped on every call by the SDK) or, when neither header is sent, from the access token alone. It is a property of the configured client, not of an individual call: the SDK carries exactly one scope and every request inherits it. That is why the check lives on Data and runs in Configure rather than per-request.

Scoping used to be a URL path segment (`/api/{namespace}/{version}/tenant/{id}`). The Platform API GA moved it to headers, and SDK v0.17.0 followed — its `APIPrefix` no longer embeds an ID, and `WithEnvironmentID` / `WithTenantID` set a header instead. Nothing in this provider builds URLs, so that transition cost no call-site changes; what it added is a second scope to choose between.

The value on a Data is read back off the SDK client via `Client.Scope()` (added in v0.18.0) rather than tracked separately, so it always reflects the header the client will actually send. See scopeFromClient for why this enum is not simply an alias of the SDK's.

const (
	// ScopeOrganization is the absence of an environment or tenant header: the
	// gateway resolves the context from the access token alone. It corresponds
	// to Jamf's *Organization management* integration scope, which covers what a
	// practitioner manages above and across individual tenants — single sign-on
	// today. AI Governance reads as organization-level and is not: it is
	// environment-scoped, wire-probed, and a request carrying no scope header is
	// refused REQUEST_CONTEXT_NOT_PROVIDED.
	//
	// It is deliberately the zero value, because a provider block setting
	// neither `environment_id` nor `tenant_id` is exactly this case.
	//
	// It is the only scope that reaches the jamfplatform_account_* family, and
	// RequireScope rejects it everywhere else. Both directions matter: an
	// organization-scoped integration pointed at a Jamf Pro resource, and an
	// environment-scoped one pointed at a Jamf Account resource, each otherwise
	// produce an opaque gateway error deep in an apply instead of a named
	// diagnostic at Configure.
	ScopeOrganization ScopeKind = iota
	// ScopeEnvironment scopes every request to a platform environment — a group
	// of tenants across product types with interconnected capabilities — sent as
	// `X-Environment-Id`. **This is the preferred scope**, and the one Jamf
	// intends new integrations to be created with. Blueprints, Compliance
	// Benchmarks and AI Governance are reachable only this way.
	ScopeEnvironment
	// ScopeTenant scopes every request to a single Jamf Pro, Jamf School, Jamf
	// Protect or Jamf Security Cloud tenant, sent as `X-Tenant-Id`. Jamf
	// describes this as the legacy method for targeting integrations without a
	// platform environment, and the Platform API GA began retiring it: six
	// Platform specs deleted the header outright, leaving Jamf Pro, ProClassic
	// and Security Cloud as the families still declaring it. Some Jamf Pro
	// surfaces remain reachable only this way, so it is supported rather than
	// deprecated — but a new integration should not be created with it. Which
	// families still accept it is resolved from the SDK registry in scopes.go
	// rather than asserted here.
	ScopeTenant
)

func ScopeOrder() []ScopeKind

func (k ScopeKind) String() string