A FinFocus plugin is a standalone binary that serves the CostSourceService
gRPC API from github.com/rshade/finfocus-spec/sdk/go/pluginsdk. The
finfocus CLI launches it, asks Supports, then calls GetProjectedCost (and
optionally GetActualCost, GetRecommendations, and others) per resource.
This repository was scaffolded by finfocus plugin init.
Rules
- Never hand-edit SDK-version state (the
finfocus-specline ingo.mod,SpecVersion, workflow pins). Runfinfocus plugin upgradeand follow thefinfocus-plugin-upgradeskill. - Never fabricate prices. If the plugin cannot price a resource, return
"not supported" from
Supportsor an error fromGetProjectedCost. Do not guess, and do not return a default. The scaffold's example rates incalculateEC2InstanceCostare placeholders: replace them. Scaffolds from finfocus v0.4.0 and earlier also default a missing instance type tot3.microand price unknown types at thet3.microrate; remove both. - Price from real data: a local pricing table with a documented source and
date, or the provider's pricing API. Record the source in
billing_detail. - Do not run
git commitorgit addunless the user asks. SpecVersionmust bev-prefixed (v0.7.2). Usepluginsdk.SpecVersion, as the scaffold does. Older scaffolds wrote a bare literal such as"0.6.1";finfocus plugin upgraderewrites it.- Never write to stdout from the plugin: the SDK prints a single
PORT=<n>handshake line there. Log to stderr or the SDK log writer.
Repo layout (from finfocus plugin init)
| Path | Purpose | Edit? |
|---|---|---|
cmd/plugin/main.go |
Builds pricing.NewCalculator() and calls pluginsdk.Serve; reads --port and FINFOCUS_PLUGIN_PORT; optional health server |
Rarely |
internal/pricing/calculator.go |
Calculator embeds *pluginsdk.BasePlugin; GetPluginInfo, Supports, GetProjectedCost, GetActualCost |
Yes, main work |
internal/pricing/data.go |
PricingData load/save helpers and example data |
Yes, if you use local tables |
internal/client/client.go |
Provider API client stub (GetResourceCost, ValidateCredentials, GetSupportedRegions) |
If you call live APIs |
internal/pricing/calculator_test.go |
Example tests using pluginsdk.NewTestPlugin |
Yes, extend |
manifest.yaml, manifest.json |
Plugin metadata (name, version, providers, capabilities) | Keep in sync |
Makefile |
build, test, lint, install, cover, security |
Rarely |
.golangci-lint.yml |
Lint config used by make lint |
No |
.github/workflows/ |
CI, release, release-please (docker, claude review when generated) | Via upgrade only |
docs/, docker/, issues.md, examples/ |
Generated docs, image, TODO list | As needed |
Binary name is finfocus-plugin-<name>; make build writes it to bin/.
Details on the SDK are in references/sdk-api.md.
Add a resource type end to end
- Find the real input. Run a plan (see Testing loop) and read what the
plugin receives. Core sends the Pulumi type token
(
aws:ec2/instance:Instance),provider,sku,region, and the resource inputs astags. Scaffolds from v0.4.0 and earlier matchaws:ec2:Instance, which core never sends; fix that case. Normalize the token in one function and test it. - Register support. Add the provider or resource type to the matcher in
NewCalculator(base.Matcher().AddProvider,AddResourceType) and extendSupports(see below). - Extract inputs. Read SKU and region from
req.GetResource(); fall back topluginsdk/mappinghelpers (ExtractAWSSKU,ExtractAzureSKU,ExtractGCPSKU, and the*Regionforms) overTags. - Price it. Compute an hourly rate and call
c.Calculator().CreateProjectedCostResponse(currency, hourly, detail), which setsCostPerMonth = hourly * 730. For a monthly price, build the response withpluginsdk.NewGetProjectedCostResponse( pluginsdk.WithProjectedCostDetails(unit, currency, monthly, detail)). - Test. Add a table-driven case for the new type, plus one unsupported and one missing-SKU case.
- Run the real loop (Testing loop) and compare the number with the provider's public price page.
- Update
manifest.yaml/manifest.jsoncapabilities if they changed and the README resource list.
Supports contract
Supports(ctx, *pbc.SupportsRequest) (*pbc.SupportsResponse, error) is the
optional SupportsProvider interface.
- Answer
Supported: falsewith aReasonrather than returning an error. Core treats an RPC error as fail-open (calls the plugin anyway). - A plugin that does not implement
Supportsgets the SDK default (Supported: false,Reason: pluginsdk.DefaultSupportsNotImplementedReason). Core treats that reason as fail-open too, so implementSupportsfor real. - Core sends provider, resource type, SKU, and region, and caches answers per client, provider, type, region, SKU, and feature. A region-bound plugin must decline other regions here so the router can pick another plugin.
- Keep it cheap and offline: no API calls.
Cost response contracts
GetProjectedCostreturnsCurrency,UnitPrice(hourly),CostPerMonth, andBillingDetail. UseBillingDetailto state assumptions (OS, tenancy, defaults applied, price source).- Validate with
pluginsdk.ValidateProjectedCostRequest(needs provider, type, SKU, region). If tags containref.*keys and SKU is empty, core validates withValidateProjectedCostRequestLenient; do the same, then price from theref.<property>.skutags or report what is missing inBillingDetail. $0is a valid priced result and does not trigger fallback to the next plugin; only an error or empty result does. Return$0only when the resource is truly free. Otherwise return an error, so another plugin can try.- Unsupported resource: return
pluginsdk.NotSupportedError(resource). No billing data:pluginsdk.NoDataError(id). - Cache hints: set
ExpiresAtwithpluginsdk.WithProjectedCostExpiresAt. Past timestamps skip caching; core caps TTLs at 7 days. - Optional extras (implement only if you can do them correctly):
GetRecommendations,GetPricingSpec,EstimateCost,BatchCost,DryRun. Seereferences/sdk-api.md.
Testing loop
make test(unit tests, in-process gRPC viapluginsdk.NewTestPlugin).- Conformance:
pluginsdk.RunBasicConformance(plugin)(also Standard and Advanced) in a test; seereferences/testing.md. make installcopies the binary to~/.finfocus/plugins/<name>/<version>/.finfocus plugin listthenfinfocus plugin validate.- Price a real plan:
finfocus cost projected --pulumi-json plan.json(create the plan withpulumi preview --json > plan.json). Add--debugto see plugin calls. make lintbefore finishing.
More in references/testing.md and references/core-contract.md.
Common pitfalls
- Core does not set
PORT. Use--portorFINFOCUS_PLUGIN_PORT; the SDK'sServehandles both and announces the chosen port on stdout. - Pulumi tokens vary (
aws:ec2/instance:Instance); never match on a single hard-coded spelling. - Nested inputs arrive as dotted tag keys (
sku.capacity,rootBlockDevice.0.volumeType) beside the collapsed key. - A mismatch between
PluginVersion,manifest.*version, and the install directory makesplugin listconfusing. Keep them equal. - A
regionkey inplugin.metadata.jsonmakes core look forfinfocus-plugin-<name>-<region>first. Region-per-binary plugins should follow that name. make installmust writeplugin.manifest.jsonas flat JSON whosenameandversionmatch the install directory, orfinfocus plugin validatefails. Scaffolds from v0.4.0 and earlier copymanifest.yamlthere instead; replace that line with the current scaffold'sprintf.