The package field exposed by VirtFusion as `primaryStorageProfile` is a
storage *type code* (mirrors `server_packages.storage_type` in the VF
database), not a profile id. It's meant to filter to any pool whose
`storageType` matches — multiple pools across the fleet can carry the
same code, which is exactly how multi-hypervisor placement works for
mountpoint/datastore storage.
`capForStorage()` was checking `pool.id` against this code. Pool ids are
unique per hypervisor (e.g. for the same logical mountpoint on three
hypervisors, ids 23/28/30) and almost never match the type-code domain
(0=local default, 4=mountpoint, etc.). The mismatch silently returned 0
for every hypervisor, zeroing qty fleet-wide whenever the package's
type code didn't accidentally collide with some pool id.
Symptoms in the wild: every stock-controlled VPS product showed qty=0
in WHMCS even with abundant memory/CPU/IPv4 capacity. Disabling
`stockcontrol` on the product or removing `primaryStorageProfile` from
the package were the only known workarounds; both lose the actual stock
gating this module is meant to provide.
Fix:
- Match `pool.storageType` instead of `pool.id`.
- Walk all pools that match (a hypervisor may have multiple pools of
the same type) and use the one that fits the most VMs, instead of
short-circuiting on the first match. A disabled pool no longer kills
the whole hypervisor's capacity for that type — we just skip it and
keep looking for an enabled peer.
- Rename the parameter from `$profileId` to `$storageTypeId` so future
readers don't fall into the same naming trap. Updated the docblock
with a NOTE explaining the VirtFusion-side naming inconsistency.
Verified on a 3-hypervisor cluster with `storageType=4` (mountpoint)
packages: qty went from 0/0/0/0/0/0/0/0 to 66/32/15/7/3/1/32/15 across
the VPS-1 through VPS-32 + storage products without any other config
change.
Opt-in per product via WHMCS's native tblproducts.stockcontrol toggle.
When enabled, the module overwrites tblproducts.qty with the number of
VPSes the panel can still actually provision, derived from two
authoritative sources:
- GET /packages/{id} for the per-VPS resource footprint (memory,
cpuCores, primaryStorage, primaryStorageProfile, enabled)
- GET /compute/hypervisors/groups/{id}/resources for live
free/allocated data per hypervisor in the group
Algorithm sums min(memory, cpu, storage) across eligible hypervisors
(enabled AND commissioned AND !prohibit) for every group the product
can be placed in (default configoption1 plus every numeric value of a
Location configurable option), capped by the group-level IPv4 pool
taken as max() within a group to avoid double-counting. Storage
matching is strict against package.primaryStorageProfile; hypervisors
without the named pool contribute 0.
FAIL-SAFE INVARIANT: transient API failures return null from
Module::fetchPackage / Module::fetchGroupResources, and the orchestrator
leaves tblproducts.qty UNCHANGED in that case. Confirmed-missing
conditions (HTTP 404, package.enabled=false) return qty=0. Without this
tri-state contract the module would either zero out inventory during
API blips, or show inventory for packages that have been deleted.
Triggers:
- AfterModuleCreate: refresh + auto-accept pending order
- AfterModuleTerminate: refresh (capacity came back)
- AfterCronJob: every-2-hour safety net for out-of-band panel changes
- ClientAreaPageCart: opportunistic per-product refresh in order flow
- admin.php?action=stockRecalculate: on-demand full recalc
Shared 30s rate-limit (stockrefresh:event) coalesces provision bursts;
60s per-product limit (stockrefresh:{pid}) caps cart-page refreshes;
grpres:{id} 120s TTL caps upstream API reads per group regardless of
how often hooks fire.
Auto-accept: AfterModuleCreate calls WHMCS AcceptOrder with
autosetup=false when the parent order is still Pending. Idempotent;
already-accepted orders are skipped via strcasecmp status check.
New per-product config option stockSafetyBufferPct (configoption7,
default 10) reserves X% of each resource's max before computing fits.
Blank falls back to 10% so existing products get headroom without any
config change. Ignored for unlimited resources (max=0) and for IPv4
(no per-hypervisor max in the response).
TestConnection now probes /compute/hypervisors/groups to surface
missing compute:read scope at config time instead of as unexplained
nightly silence.
