ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Collect what bays actually have, separately from what they are told to have
Some checks failed
CI / backend (push) Failing after 7m15s
Details
CI / naming (push) Failing after 7m22s
Details
CI / frontend (push) Failing after 7m14s
Details
CI / migrations-mysql (push) Failing after 7m14s
Details

Browse Source 
ShopDB knew what a bay SHOULD have and nothing about what it DOES. Adding the
observed half makes a rollout a review instead of a typing exercise: the floor
reports itself in, you look, and you adopt.

The collection uses the mechanism that already exists rather than a new one.
POST /api/collector/printers dispatches to the printers plugin's
apply_collector_payload, the same ADR-006 hook the computers and backups plugins
implement. New client script, new plugin-owned table, no new transport and no new
credential.

OBSERVED AND ASSIGNED STAY APART, and that is the point rather than a detail. A
collector report can never write an assignment row: _reconcile_edges is the only
function that writes usesprinter/defaultprinter, it has two call sites, and both
are authenticated routes a human calls. If a drifted bay's own state were allowed
to become what it is told to install, every configuration error would become
permanent the next time that PC checked in.

Seeding an assignment from observed state is explicit -
POST /assignments/seed-from-observed - because a rollout adopts many machines at
once. It routes through the same _reconcile_edges as the editor, so there is one
write path with two doors, and a queue matching no known printer is REFUSED
rather than guessed into an assignment. That last rule is the lesson from the
measuring tools: adopting on a weak key produced 43 duplicate instruments.

Two fixes on top of what the agents built. The replace deleted a host's previous
rows by exact case-folded name while the read path treats a short name and its
FQDN as one machine, so a PC that changed spelling appeared to hold every queue
twice - which reads as drift that is not there. And the client sent 'reportedat'
where the declared schema said 'observedat'.

Also here: the legacy loader now imports machines.printerid, the classic system's
record of each machine's default printer, which it silently dropped - the
production import would have lost every one. And Set-ShopdbPrinters.ps1 finally
registers the per-user logon task, staging Apply-ShopdbDefaultPrinter.ps1 to
C:\ProgramData first because the share it lives on is mounted only during the
enforcement cycle and the task runs at logon when it is gone.

VALIDATED ON WINDOWS 11 (build 26200), not just on Linux pwsh, which parses these
scripts happily and executes none of the spooler branches.

The reporter: posts a correct payload with the X-API-Key header; resolves BaseUrl
and CollectorKey from HKLM when given no arguments; suppresses the virtual queues
by port; resolves port addresses; and reads the CONSOLE USER's default out of
HKU rather than SYSTEM's own, which is a different and usually wrong answer.

Two results matter more than the rest. With the spooler stopped, both the cmdlet
and the CIM path fail and the script posts NOTHING - verified against a capture
server that recorded zero requests, where an empty list would instead have
erased that host's observed rows and read as a bay that lost its printers. A
genuinely empty host still posts [], because that is a real and different fact.

The logon task registers as the Users group at Limited, and falls back to the
well-known SID S-1-5-32-545 when the group name will not resolve, as it will not
on localised Windows. It was then run with the source directory RENAMED AWAY, to
stand in for the share being unmounted, and it still moved the user's default -
which is the whole reason the script is staged to C:\ProgramData rather than run
from where it lives.

The guarantees against damage were re-checked rather than assumed: an empty
assignment changes nothing, an unreachable server changes nothing, -WhatIfOnly
leaves no queue, no task, no staged file and no registry value behind, and a
drifted queue is repointed IN PLACE with Set-Printer so whoever has it as their
default keeps it.

Not covered by any of this: the driver-staging path, which needs a real vendor
package rather than the class drivers a VM ships with.
This commit is contained in:
cproudlock
2026-08-19 14:45:39 -04:00
parent 1a5a1cd43d
commit 2d09fa3201
15 changed files with 2903 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

653
plugins/printers/api/asset_routes.py
View File

@@ -8,7 +8,7 @@ from flask_jwt_extended import jwt_required
from shopdb.api import db, cache, Setting, Asset, AssetType, Vendor, Model, Communication, CommunicationType, AssetRelationship, RelationshipType, success_response, error_response, paginated_response, ErrorCodes, get_pagination_params, paginate_query
from ..models import Printer, PrinterType, ModelSupply, PrinterDriver
from ..models import Printer, PrinterType, ModelSupply, PrinterDriver, PrinterObservedQueue
from ..models.model_supply import SUPPLY_TYPES, SUPPLY_COLORS, CAPACITY_TIERS
from ..services import (
ZabbixService,
@@ -1136,6 +1136,657 @@ def _reconcile_edges(sourceassetid, writetypeid, readtypeids, wantedtargets):
relationshiptypeid=writetypeid,
isactive=True))
# =============================================================================
# Observed state (what a bay actually has)
# =============================================================================
# The other half of the loop. The assignment says what a host SHOULD have; the
# observed rows say what it reported having on its last cycle, and they are kept
# apart on purpose - the moment a drifted bay's observed state is treated as
# correct, enforcement stops meaning anything. Nothing here writes an assignment
# except the seed endpoint at the bottom, which a person has to ask for.
_OBSERVED_MATCHING = 'matching'
_OBSERVED_MISSING = 'missing'
_OBSERVED_EXTRA = 'extra'
_OBSERVED_DRIFTED = 'drifted'
_OBSERVED_UNKNOWN = 'unknown'
_OBSERVED_CLASSIFICATIONS = (_OBSERVED_MATCHING, _OBSERVED_MISSING,
_OBSERVED_EXTRA, _OBSERVED_DRIFTED,
_OBSERVED_UNKNOWN)
def _observed_rows(hostname):
"""The rows of a host's last report, or [].
Case-folded with the same short-name and FQDN fallbacks as
_computer_by_hostname: the reporter sends its own COMPUTERNAME, and whether
that is short or fully qualified is a matter of how the site enrolls PCs,
not of which host it is.
Ordered by queue name, not by insertion: a report replaces the previous one
in one pass, so row order carries no meaning, and a stable sort keeps two
reads of the same report - and the seed built from it - identical.
"""
name = (hostname or '').strip().lower()
if not name:
return []
query = PrinterObservedQueue.query.order_by(PrinterObservedQueue.queuename)
rows = query.filter(db.func.lower(PrinterObservedQueue.hostname) == name).all()
if rows:
return rows
shortname = name.split('.')[0]
if shortname != name:
rows = query.filter(
db.func.lower(PrinterObservedQueue.hostname) == shortname).all()
if rows:
return rows
# Prefix match only for a plain hostname, as in _computer_by_hostname: a
# LIKE wildcard arriving in the path segment would pull back another PC.
if not re.match(r'^[a-z0-9-]+$', shortname):
return []
return query.filter(
db.func.lower(PrinterObservedQueue.hostname).like(shortname + '.%')).all()
def _printer_match_index():
"""Lookup tables for turning an observed queue into a printer asset.
Built in two queries instead of one lookup per queue, and built in
printerid order so first-match is deterministic: two printers can share an
address (a multi-queue device, or a Communication row left behind by a
swap), and without a fixed order the same report would classify one way on
one read and another way on the next.
'addressof' is what an install would point the port at - hostname first, IP
second, the order Set-ShopdbPrinters uses - and 'addressesof' is every
address that IS this printer. Drift is judged against the set, not the
preferred one: a queue pointed at the printer's IP where the register names
its hostname reaches the same device, and calling that drift would light up
every correctly installed bay.
"""
rows = (db.session.query(Printer, Asset)
.join(Asset, Asset.assetid == Printer.assetid)
.filter(Asset.isactive == True)
.order_by(Printer.printerid)
.all())
communications = {}
assetids = [printer.assetid for printer, _asset in rows]
if assetids:
for communication in (Communication.query
.filter(Communication.assetid.in_(assetids))
.order_by(Communication.communicationid).all()):
communications.setdefault(communication.assetid, []).append(communication)
index = {'byaddress': {}, 'byqueuename': {}, 'printers': {},
'addressof': {}, 'addressesof': {}}
for printer, asset in rows:
index['printers'][printer.assetid] = (printer, asset)
own = communications.get(printer.assetid, [])
primary = next((item for item in own if item.isprimary), None)
if primary is None and own:
primary = own[0]
address = (printer.hostname or '').strip()
if not address and primary is not None:
address = (primary.ipaddress or '').strip()
index['addressof'][printer.assetid] = address or None
# Every address the printer answers on, not just the primary one: a
# second NIC still identifies the same device to a port that uses it.
addresses = set()
for value in [printer.hostname] + [item.ipaddress for item in own]:
key = (value or '').strip().lower()
if key:
addresses.add(key)
index['byaddress'].setdefault(key, printer.assetid)
index['addressesof'][printer.assetid] = addresses
for value in (printer.windowsname, printer.sharename,
_install_name(printer, asset),
asset.assetnumber, asset.name):
key = (value or '').strip().lower()
if key:
index['byqueuename'].setdefault(key, printer.assetid)
return index
def _match_observed_queue(row, index):
"""The printer assetid an observed queue is, or None.
PORT ADDRESS first. An IP or FQDN names one device and cannot be reused by
a differently-named queue on the next bay, so it is the only key worth
trusting. The Windows PORT NAME is looked up in the same address table
because a standard TCP/IP port created outside the client is named after the
host address itself - that is still an exact match on an address ShopDB
holds, not a guess at one.
Queue name second, and nothing after it. An unmatched queue is reported as
unknown: a wrong match seeds a wrong assignment, which is worse than no
assignment at all.
"""
for value in (row.portaddress, row.portname):
key = (value or '').strip().lower()
if key and key in index['byaddress']:
return index['byaddress'][key]
return index['byqueuename'].get((row.queuename or '').strip().lower())
def _assigned_expectations(assignment, index):
"""{printer assetid: what an install of it would look like}.
Keyed off the resolved assignment, so a PC that inherits its bay's printers
is compared against the bay's, which is what the client would have
installed. An assigned asset that is retired or is not a printer is left out
entirely: for-host skips it too, so a bay cannot be missing it.
"""
expected = {}
assignments = assignment.get('assignments') or []
if not assignments:
return expected
universaldrivers = (PrinterDriver.query
.filter(PrinterDriver.modelnumberid.is_(None),
PrinterDriver.isactive == True)
.order_by(PrinterDriver.name).all())
for item in assignments:
entry = index['printers'].get(item['assetid'])
if entry is None:
continue
printer, asset = entry
driver = _printer_driver(printer, universaldrivers)
expected[printer.assetid] = {
'printerid': printer.printerid,
'printerassetid': printer.assetid,
'printername': asset.name or asset.assetnumber,
'queuename': _install_name(printer, asset),
'portaddress': index['addressof'].get(printer.assetid),
'addresses': index['addressesof'].get(printer.assetid) or set(),
'drivername': driver.drivername if driver else None,
'isdefault': bool(item.get('isdefault')),
'inheritedfromassetid': item.get('inheritedfromassetid'),
}
return expected
def _observed_driftfields(row, want):
"""Which installed properties disagree with the assignment.
Port address and driver name only. A queue NAME that differs is reported -
expectedqueuename is in the payload - but is not drift: the port says it is
the same device, and a locally renamed queue still prints to it, so renaming
it back is a preference rather than a fault.
The address is judged against every address the printer answers on rather
than against the one an install would prefer, because hostname and IP are
the same device. Address drift is therefore a queue that carries the
printer's NAME while printing somewhere else - the failure that is invisible
from the server and obvious to whoever is standing at the machine.
A queue with no port address (a non-TCP port, or a reporting host too old to
read one) cannot be compared on address, so only its driver is judged.
Comparing against a blank would report every such queue as drifted and the
view would be noise.
"""
fields = []
observedaddress = (row.portaddress or '').strip().lower()
addresses = want.get('addresses') or set()
if observedaddress and addresses and observedaddress not in addresses:
fields.append('portaddress')
observeddriver = (row.drivername or '').strip().lower()
wanteddriver = (want['drivername'] or '').strip().lower()
if observeddriver and wanteddriver and observeddriver != wanteddriver:
fields.append('drivername')
return fields
def _observed_entry(row=None, want=None, classification=None, printer=None,
asset=None, driftfields=None):
"""One row of the comparison, observed side and assigned side in one shape.
Both sides in every entry so a reviewer never has to join two lists: a
missing printer has no observed half, an unknown queue has no assigned half,
and everything in between carries what it has and nulls for what it lacks.
"""
return {
'classification': classification,
'queuename': (row.queuename if row is not None
else (want or {}).get('queuename')),
'drivername': row.drivername if row is not None else None,
'portname': row.portname if row is not None else None,
'portaddress': row.portaddress if row is not None else None,
'isdefault': bool(row.isdefault) if row is not None else False,
'isshared': bool(row.isshared) if row is not None else False,
'printerid': (printer.printerid if printer is not None
else (want or {}).get('printerid')),
'printerassetid': (printer.assetid if printer is not None
else (want or {}).get('printerassetid')),
'printername': ((asset.name or asset.assetnumber) if asset is not None
else (want or {}).get('printername')),
'expectedqueuename': (want or {}).get('queuename'),
'expectedportaddress': (want or {}).get('portaddress'),
'expecteddrivername': (want or {}).get('drivername'),
'isassigneddefault': bool((want or {}).get('isdefault')),
'inheritedfromassetid': (want or {}).get('inheritedfromassetid'),
'driftfields': driftfields or [],
}
def _observed_comparison(rows, expected, index):
"""Every observed queue classified, then the assigned printers nobody saw.
matching - assigned, present, installed the way the assignment says.
drifted - assigned and present, but on another port or another driver.
extra - a printer ShopDB knows, installed here without being assigned.
missing - assigned, and the host did not report it.
unknown - a queue that matches no printer in ShopDB.
"""
queues = []
seen = set()
for row in rows:
printerassetid = _match_observed_queue(row, index)
if printerassetid is None:
queues.append(_observed_entry(row=row, classification=_OBSERVED_UNKNOWN))
continue
printer, asset = index['printers'][printerassetid]
want = expected.get(printerassetid)
if want is None:
queues.append(_observed_entry(row=row, classification=_OBSERVED_EXTRA,
printer=printer, asset=asset))
continue
seen.add(printerassetid)
driftfields = _observed_driftfields(row, want)
queues.append(_observed_entry(
row=row, want=want, printer=printer, asset=asset,
driftfields=driftfields,
classification=_OBSERVED_DRIFTED if driftfields else _OBSERVED_MATCHING))
for printerassetid, want in expected.items():
if printerassetid not in seen:
queues.append(_observed_entry(want=want, classification=_OBSERVED_MISSING))
return queues
def _seed_candidate(queues):
"""The assignment a seed would write, and the queues it would refuse.
Matched queues only, in the order _observed_rows returns them. The observed
default carries over only when it matched a printer: a default outside the
set is rejected by the assignment writer anyway, and pointing a bay at a
queue it was never told to install fails on the bay with nothing in ShopDB
saying why.
"""
printerassetids = []
skipped = []
defaultprinterassetid = None
for entry in queues:
if entry['classification'] == _OBSERVED_MISSING:
continue
if entry['classification'] == _OBSERVED_UNKNOWN:
skipped.append({
'queuename': entry['queuename'],
'drivername': entry['drivername'],
'portname': entry['portname'],
'portaddress': entry['portaddress'],
'isdefault': entry['isdefault'],
})
continue
if entry['printerassetid'] not in printerassetids:
printerassetids.append(entry['printerassetid'])
if entry['isdefault'] and defaultprinterassetid is None:
defaultprinterassetid = entry['printerassetid']
return {
'printerassetids': printerassetids,
'defaultprinterassetid': defaultprinterassetid,
'skipped': skipped,
}
def _observed_summary(queues):
counts = {name: 0 for name in _OBSERVED_CLASSIFICATIONS}
for entry in queues:
counts[entry['classification']] += 1
return counts
def _observed_host_block(hostname, asset, index):
"""One host's report, classified against what that host would install.
The assigned side is resolved from the REPORTING PC, not from whatever asset
a caller asked about: a PC's own rows shadow the machine's, so a bay with an
override is converged when it matches the override. `source` says which of
the two the comparison used.
"""
rows = _observed_rows(hostname)
assignment = (resolve_asset_printers(asset) if asset is not None
else {'assignments': [], 'source': 'none'})
queues = _observed_comparison(rows, _assigned_expectations(assignment, index),
index)
# One report is written in one pass, so every row carries the same stamp.
observedat = rows[0].observedat if rows else None
return {
'hostname': hostname,
'assetid': asset.assetid if asset is not None else None,
'assetnumber': asset.assetnumber if asset is not None else None,
'source': assignment['source'],
'observedat': observedat.isoformat() if observedat else None,
'queues': queues,
'summary': _observed_summary(queues),
'seedcandidate': _seed_candidate(queues),
}
@printers_asset_bp.route('/observed/<hostname>', methods=['GET'])
@jwt_required()
@require_permission('printers.view')
def observed_for_host(hostname: str):
"""What a host last reported, each queue judged against what it is assigned.
The mirror of for-host: that endpoint says what this bay SHOULD have, this
one says what it told us it DOES have, and puts the two side by side. Read
only - nothing here changes an assignment, however wrong the bay looks.
404 only when the hostname means nothing here: no report and no computer. A
known PC that has never reported is an empty queue list, and a report from a
host with no computer record still comes back - everything on it is extra or
unknown, which is exactly the answer a technician needs.
`seedcandidate` is a preview of what POST
/api/printers/assignments/seed-from-observed would write from this report.
"""
try:
found = _computer_by_hostname(hostname)
except ImportError:
# No computers plugin, so no hostname -> asset resolution and no
# assigned side. The report itself is still worth returning.
found = None
rows = _observed_rows(hostname)
if not rows and not found:
return error_response(
ErrorCodes.NOT_FOUND,
f'No printer report and no computer for hostname {hostname}',
http_code=404)
computer, asset = found if found else (None, None)
known = (computer.hostname if computer is not None
else (rows[0].hostname if rows else hostname))
return success_response(_observed_host_block(known, asset, _printer_match_index()))
@printers_asset_bp.route('/observed/for-asset/<int:asset_id>', methods=['GET'])
@jwt_required()
@require_permission('printers.view')
def observed_for_asset(asset_id: int):
"""The same comparison, reached from an asset page: one block per host.
Assigned state lives on the MACHINE and observed state is reported by the
PCs, so a machine answers with a block for each PC that controls it. Blocks
rather than one merged list because a dualpath pair or a part marker
legitimately puts two PCs on one machine, and the only actionable thing
about drift is which box to walk to.
An asset nothing reports for - a machine with no PC, or a PC with no
computer record - is an empty `hosts` list and a 200. This hangs off the
asset page, and on the day it ships most bays have not reported yet.
"""
asset = db.session.get(Asset, asset_id)
if not asset or not asset.isactive:
return error_response(ErrorCodes.NOT_FOUND, 'Asset not found', http_code=404)
hosts = []
seen = set()
own = _own_hostname(asset)
if own:
hosts.append((own, asset))
seen.add(own.lower())
for hostname, pcasset in _controlling_computers(asset_id):
if hostname.lower() not in seen:
seen.add(hostname.lower())
hosts.append((hostname, pcasset))
index = _printer_match_index()
return success_response({
'assetid': asset_id,
'assetnumber': asset.assetnumber,
'hosts': [_observed_host_block(hostname, pcasset, index)
for hostname, pcasset in hosts],
})
def _controlling_computers(assetid):
"""(hostname, PC asset) for the active PCs that control this asset.
Observed state is reported by the PC and the assignment belongs to the
machine, so both the comparison and a seed onto a machine have to cross the
controls edge. Read incoming here (PC -> machine) because the machine is the
asset being asked about, which is the same edge resolve_asset_printers walks
outgoing. Oldest edge first, so two PCs on one machine list in a fixed
order.
"""
try:
from plugins.computers.models import Computer
except ImportError:
return []
typeids = _relationship_typeids(_CONTROLS)[_CONTROLS]
if not typeids:
return []
rows = (db.session.query(Computer.hostname, Asset)
.select_from(AssetRelationship)
.join(Computer, Computer.assetid == AssetRelationship.sourceassetid)
.join(Asset, Asset.assetid == Computer.assetid)
.filter(AssetRelationship.targetassetid == assetid,
AssetRelationship.relationshiptypeid.in_(typeids),
AssetRelationship.isactive == True,
Asset.isactive == True)
.order_by(AssetRelationship.relationshipid)
.all())
controllers = []
seen = set()
for hostname, pcasset in rows:
key = (hostname or '').strip().lower()
if not key or key in seen:
continue
seen.add(key)
controllers.append((hostname, pcasset))
return controllers
def _own_hostname(asset):
"""The asset's own hostname when it is a PC, else None."""
try:
from plugins.computers.models import Computer
except ImportError:
return None
computer = Computer.query.filter_by(assetid=asset.assetid).first()
if computer is None or not computer.hostname:
return None
return computer.hostname
def _seed_source_hostnames(asset):
"""Hosts whose report could seed this asset: its own, then its controllers.
Its own first because seeding a PC from a different PC's report is never
what was meant; the controllers because the normal target is the MACHINE,
which reports nothing itself.
"""
hostnames = []
own = _own_hostname(asset)
if own:
hostnames.append(own)
for hostname, _pcasset in _controlling_computers(asset.assetid):
if hostname.lower() not in [name.lower() for name in hostnames]:
hostnames.append(hostname)
return hostnames
@printers_asset_bp.route('/assignments/seed-from-observed/<int:asset_id>',
methods=['POST'])
@jwt_required()
@require_permission('printers.edit')
def seed_assignment_from_observed(asset_id: int):
"""Write what a PC observed as the assignment of the asset in the path.
THE ONE PATH FROM OBSERVED TO ASSIGNED, and a person has to ask for it. No
collector, no cycle and no background job reaches this route: a bay that
installed the wrong printer must never be able to make itself right by
reporting it. The reviewer reads the comparison (GET
/api/printers/observed/<hostname>, or /observed/for-asset/<id> from an asset
page), agrees with it, and posts here.
Normally posted against the MACHINE, so the assignment survives a reimage
and follows the bay (see resolve_asset_printers); posting it against the PC
works and is warned about, because the PC's own rows then shadow the
machine's for good.
Body, all optional:
{"hostname": "PC01", which report to seed from. Omitted, the asset's
own hostname or its single controlling PC.
"allowunmatched": false} proceed when some queue matches no printer.
Refuses rather than guesses:
409 when more than one controlling PC has reported - which bay is right is
not something this endpoint can know.
409 when any queue matches no printer, listing every one of them, unless
allowunmatched says to seed the rest anyway.
400 when nothing matched, because writing the empty set would silently
unassign the asset.
Nothing is written on any of those; the assignment is left exactly as found.
"""
asset = db.session.get(Asset, asset_id)
if not asset or not asset.isactive:
return error_response(ErrorCodes.NOT_FOUND, 'Asset not found', http_code=404)
data = request.get_json(silent=True) or {}
hostname = (data.get('hostname') or '').strip()
allowunmatched = bool(data.get('allowunmatched'))
if hostname:
rows = _observed_rows(hostname)
if not rows:
return error_response(
ErrorCodes.NOT_FOUND,
f'No printer report from hostname {hostname}',
http_code=404)
else:
reporting = [name for name in _seed_source_hostnames(asset)
if _observed_rows(name)]
if not reporting:
return error_response(
ErrorCodes.NOT_FOUND,
'No host has reported printers for this asset - name one with '
'{"hostname": "..."}',
http_code=404)
if len(reporting) > 1:
return error_response(
ErrorCodes.CONFLICT,
'Several hosts report printers for this asset - name the one to '
'seed from',
details={'hostnames': reporting},
http_code=409)
hostname = reporting[0]
rows = _observed_rows(hostname)
index = _printer_match_index()
# Classified with no assigned side: seeding asks what each queue IS, not
# whether the asset already has it. The reconcile below is the whole set.
queues = _observed_comparison(rows, {}, index)
candidate = _seed_candidate(queues)
if candidate['skipped'] and not allowunmatched:
return error_response(
ErrorCodes.CONFLICT,
'{0} observed queue(s) match no printer in ShopDB. Add them as '
'printer assets, or repost with allowunmatched to seed the '
'rest.'.format(len(candidate['skipped'])),
details={
'hostname': hostname,
'skipped': candidate['skipped'],
'printerassetids': candidate['printerassetids'],
},
http_code=409)
if not candidate['printerassetids']:
return error_response(
ErrorCodes.VALIDATION_ERROR,
f'Nothing to seed: no queue reported by {hostname} matches a printer '
'in ShopDB',
details={'hostname': hostname, 'skipped': candidate['skipped']})
typeids = _relationship_typeids(_USES_PRINTER, _DEFAULT_PRINTER, _CONTROLS)
if not typeids[_USES_PRINTER] or not typeids[_DEFAULT_PRINTER]:
return error_response(
ErrorCodes.INTERNAL_ERROR,
'Relationship types are not seeded - run: flask seed reference-data',
http_code=500)
warnings = []
observeddefault = next((entry for entry in queues if entry['isdefault']), None)
if observeddefault is not None and candidate['defaultprinterassetid'] is None:
warnings.append(
'Default queue "{0}" matches no printer in ShopDB; no default '
'assigned'.format(observeddefault['queuename']))
elif observeddefault is None:
warnings.append(f'{hostname} reported no default printer; no default assigned')
if candidate['skipped']:
warnings.append('{0} unmatched queue(s) were not assigned'.format(
len(candidate['skipped'])))
if _outgoing_rows(asset_id, typeids[_CONTROLS]):
# Own rows shadow rather than merge, so seeding the PC of a bay quietly
# takes that bay off the machine's assignment for good.
warnings.append(
'This asset controls another asset: its own printers now shadow the '
'assignment of the machine it controls')
_reconcile_edges(asset_id, typeids[_USES_PRINTER][0],
typeids[_USES_PRINTER], candidate['printerassetids'])
_reconcile_edges(asset_id, typeids[_DEFAULT_PRINTER][0],
typeids[_DEFAULT_PRINTER],
[candidate['defaultprinterassetid']]
if candidate['defaultprinterassetid'] is not None else [])
db.session.commit()
printerassetids, defaultassetid = _own_assignment(asset_id, typeids)
logger.info('Seeded printer assignment for asset %s from %s: %d printer(s), '
'%d skipped', asset_id, hostname, len(printerassetids),
len(candidate['skipped']))
return success_response({
'assetid': asset_id,
'seededfromhostname': hostname,
'printerassetids': printerassetids,
'defaultprinterassetid': defaultassetid,
'skipped': candidate['skipped'],
'warnings': warnings,
}, message='Printer assignment seeded from observed state')
@printers_asset_bp.route('/<int:printer_id>', methods=['GET'])
@jwt_required(optional=True)
def get_printer(printer_id: int):

314
plugins/printers/client/Report-PrintersToShopDB.ps1 Normal file
View File

@@ -0,0 +1,314 @@
# Report-PrintersToShopDB.ps1
#
# Reports the print queues this PC ACTUALLY has to ShopDB, so the register can
# be compared against what the bay is SUPPOSED to have. ShopDB knows the
# assignment (GET /api/printers/for-host/<hostname>, applied by
# Set-ShopdbPrinters.ps1); it has never known what is really installed. This is
# that missing half.
#
# TARGET: the ADR-006 collector API.
# POST <shopdb>/api/collector/printers
# The server is NOT baked in. It comes from HKLM:\SOFTWARE\GE\ShopDB BaseUrl,
# which Install-GEEnforce.ps1 provisions and the enforcement client already
# needs, or from -ApiUrl in the manifest entry's Args. ADR-015: a site name in
# product code is a defect, and this script ships to every site.
#
# READ ONLY. It calls nothing that creates, changes or removes a queue, a port
# or a driver - only Get-*. Convergence is Set-ShopdbPrinters.ps1's job and
# stays there; a reporter that also fixes things cannot be trusted to tell you
# what was broken.
#
# OBSERVED IS NOT ASSIGNED. The server stores this in its own table and never
# turns it into an assignment on its own. A drifted bay reporting its drift must
# not be able to redefine what correct means.
#
# THE LATEST REPORT REPLACES THE PREVIOUS ONE for this hostname, which makes an
# empty queues list a legitimate "this bay has no printers" and wipes the host's
# observed rows. So a FAILED enumeration must send NOTHING rather than an empty
# list - see the $enumerated flag below. Reporting nothing loses one cycle;
# reporting [] after a WMI hiccup deletes real state and reads as a bay that
# lost its printers.
#
# AUTH: the collector API does NOT honor the GE-Enforce IP allowlist (that only
# covers the geenforce fetch/report endpoints). It needs a collector.ingest key,
# sent as the X-API-Key header. The key is read from HKLM:\SOFTWARE\GE\ShopDB
# CollectorKey (the same secret store Report-AssetToShopDB.ps1 uses; provisioned
# at imaging), or overridden via the manifest entry's Args -ApiKey. Never bake
# the key into the manifest JSON on the share.
#
# Runs every GE-Enforce cycle as a Type=PS1 / DetectionMethod=Always entry under
# the SYSTEM task. Always exits 0 so a printer problem never fails an
# enforcement run; failures are logged, never thrown.
param(
# Flask collector endpoint for the printers plugin. Empty resolves from
# HKLM:\SOFTWARE\GE\ShopDB BaseUrl; override here if the path ever moves.
[string]$ApiUrl = '',
# collector.ingest key (X-API-Key). Default: read from the GE-Enforce secret
# store in the registry. Override with -ApiKey via Args for testing.
[string]$ApiKey = '',
# Identity field of the payload. Defaults to this machine's name, which is
# what the assignment side (for-host) and the computers collector both key on.
[string]$Hostname = $env:COMPUTERNAME,
[int]$TimeoutSec = 30,
# Enumerate and log the payload, post nothing. For proving what a bay would
# report before a site is pointed at a live server.
[switch]$WhatIfOnly
)
$ErrorActionPreference = 'Continue'
# Force TLS 1.2 - older images default to SystemDefault which may negotiate a
# protocol the site rejects; the collector POST is HTTPS.
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$logDir = 'C:\Logs\Shopfloor'
if (-not (Test-Path $logDir)) {
New-Item -ItemType Directory -Path $logDir -Force -ErrorAction SilentlyContinue | Out-Null
}
$logFile = Join-Path $logDir ('report-printers-{0}.log' -f (Get-Date -Format 'yyyyMMdd'))
function Log([string]$msg) {
$ts = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
"$ts $msg" | Tee-Object -FilePath $logFile -Append | Out-Null
}
$REGPATHS = @('HKLM:\SOFTWARE\GE\ShopDB', 'HKLM:\SOFTWARE\WOW6432Node\GE\ShopDB')
function Get-ShopdbRegValue([string]$name) {
foreach ($path in $REGPATHS) {
try {
if (Test-Path $path) {
$value = [string](Get-ItemProperty -Path $path -Name $name -ErrorAction Stop).$name
if ($value -and $value.Trim()) { return $value.Trim() }
}
} catch {}
}
return ''
}
Log "=== Report printers to ShopDB (collector) : $Hostname ==="
# Server from the GE-Enforce config hive when not passed via Args. Any site
# running this script is running the enforcement client, which cannot work
# without BaseUrl, so it is present wherever this is deployed.
if (-not $ApiUrl) {
$base = Get-ShopdbRegValue 'BaseUrl'
if ($base) { $ApiUrl = $base.TrimEnd('/') + '/api/collector/printers' }
}
if (-not $ApiUrl -and -not $WhatIfOnly) {
Log 'ERROR no ShopDB URL (HKLM:\SOFTWARE\GE\ShopDB BaseUrl or -ApiUrl). Skipping.'
exit 0
}
# collector key from the GE-Enforce secret store when not passed via Args.
if (-not $ApiKey) { $ApiKey = Get-ShopdbRegValue 'CollectorKey' }
if (-not $ApiKey -and -not $WhatIfOnly) {
Log 'ERROR no collector key (HKLM:\SOFTWARE\GE\ShopDB CollectorKey or -ApiKey). Skipping.'
exit 0
}
# Queues that are not devices: the Windows-supplied virtual printers plus the
# Office writers. They exist on every image, match nothing in the register, and
# would each land as an UNKNOWN row on every bay in the fleet.
#
# Matched on the PORT, not the queue name, because the name is whatever a user
# renamed it to while the port of a virtual device is fixed. Two of them are
# matched on driver as well, since a redirected-port queue can share PORTPROMPT.
$VIRTUALPORTS = @('PORTPROMPT:', 'SHRFAX:', 'XPSPort:', 'nul:', 'NUL:')
$VIRTUALDRIVERS = @(
'Microsoft XPS Document Writer',
'Microsoft XPS Document Writer v4',
'Microsoft Print To PDF',
'Microsoft Shared Fax Driver',
'Send to Microsoft OneNote Driver',
'Microsoft Software Printer Driver'
)
function Test-VirtualQueue([string]$portname, [string]$drivername) {
foreach ($p in $VIRTUALPORTS) {
if ($portname -and $portname.Trim().ToLower() -eq $p.ToLower()) { return $true }
}
# OneNote's port is a per-install GUID path, so it can only be caught here.
if ($portname -and $portname -like 'Microsoft.Office.OneNote*') { return $true }
foreach ($d in $VIRTUALDRIVERS) {
if ($drivername -and $drivername.Trim().ToLower() -eq $d.ToLower()) { return $true }
}
return $false
}
# Port address is the primary match key server-side: an IP or FQDN is
# unambiguous where a queue name is a local habit. Built once as a lookup so a
# bay with 8 queues does not re-enumerate ports 8 times.
#
# A port with no host address (USB, WSD, a redirected port) reports a null
# address and matches on name alone, which is correct: a locally attached
# printer is still a real printer worth seeing.
$portAddresses = @{}
$portsRead = $false
try {
foreach ($port in (Get-PrinterPort -ErrorAction Stop)) {
$address = ''
if ($port.PSObject.Properties['PrinterHostAddress']) {
$address = [string]$port.PrinterHostAddress
}
if ($port.Name) { $portAddresses[[string]$port.Name] = $address.Trim() }
}
$portsRead = $true
} catch {
Log "WARN Get-PrinterPort failed, falling back to WMI ports: $($_.Exception.Message)"
}
if (-not $portsRead) {
# PS 5.1-era hosts without the PrintManagement module, and images where the
# spooler cmdlets are broken but WMI still answers.
try {
foreach ($port in (Get-CimInstance -ClassName Win32_TCPIPPrinterPort -ErrorAction Stop)) {
if ($port.Name) { $portAddresses[[string]$port.Name] = ([string]$port.HostAddress).Trim() }
}
$portsRead = $true
} catch {
# Not fatal: queues still report, just without an address to match on.
Log "WARN could not read printer ports at all: $($_.Exception.Message)"
}
}
# The queues themselves. $enumerated stays false unless a read actually
# succeeded, because "no queues" and "could not look" are the same empty list
# and the server treats them very differently (see the header).
$queues = @()
$enumerated = $false
try {
foreach ($printer in (Get-Printer -ErrorAction Stop)) {
$queues += [pscustomobject]@{
queuename = [string]$printer.Name
drivername = [string]$printer.DriverName
portname = [string]$printer.PortName
}
}
$enumerated = $true
} catch {
Log "WARN Get-Printer failed, falling back to WMI queues: $($_.Exception.Message)"
}
if (-not $enumerated) {
try {
foreach ($printer in (Get-CimInstance -ClassName Win32_Printer -ErrorAction Stop)) {
$queues += [pscustomobject]@{
queuename = [string]$printer.Name
drivername = [string]$printer.DriverName
portname = [string]$printer.PortName
}
}
$enumerated = $true
} catch {
Log "ERROR could not enumerate printers: $($_.Exception.Message)"
}
}
if (-not $enumerated) {
# Deliberately posts nothing. An empty report REPLACES this host's observed
# rows, so a failed read must not be able to claim the bay has no printers.
Log 'ERROR enumeration failed; posting NOTHING so the last good report stands.'
exit 0
}
# Which queue the interactive user actually prints to. This process is SYSTEM,
# and the default printer is per user, so Win32_Printer.Default here describes
# the SYSTEM session and is usually wrong. Read the console user's own value
# first: HKU\<sid>\...\Windows Device holds "<queue>,winspool,<port>".
$defaultName = ''
try {
$consoleUser = [string](Get-CimInstance -ClassName Win32_ComputerSystem -ErrorAction Stop).UserName
if ($consoleUser) {
$sid = (New-Object System.Security.Principal.NTAccount($consoleUser)).Translate(
[System.Security.Principal.SecurityIdentifier]).Value
$devicePath = "Registry::HKEY_USERS\$sid\Software\Microsoft\Windows NT\CurrentVersion\Windows"
$device = [string](Get-ItemProperty -Path $devicePath -Name Device -ErrorAction Stop).Device
if ($device) { $defaultName = ($device -split ',')[0].Trim() }
if ($defaultName) { Log "default for $consoleUser : $defaultName" }
}
} catch {
# Nobody logged on, a roaming hive not loaded, or a name that will not
# translate. Not worth a warning every cycle on an unattended bay.
}
if (-not $defaultName) {
# Falls back to whatever this session sees. Marked in the log because a
# SYSTEM-session default is weak evidence and a reviewer should know which
# one they are looking at before seeding an assignment from it.
try {
$sysDefault = Get-CimInstance -ClassName Win32_Printer -ErrorAction Stop |
Where-Object { $_.Default } | Select-Object -First 1
if ($sysDefault) {
$defaultName = [string]$sysDefault.Name
Log "default from the SYSTEM session (no console user): $defaultName"
}
} catch {}
}
$reported = @()
$skipped = 0
foreach ($queue in $queues) {
if (-not $queue.queuename) { continue }
if (Test-VirtualQueue $queue.portname $queue.drivername) { $skipped++; continue }
$portAddress = ''
if ($queue.portname -and $portAddresses.ContainsKey($queue.portname)) {
$portAddress = [string]$portAddresses[$queue.portname]
}
$row = @{
queuename = $queue.queuename
isdefault = ($defaultName -and $queue.queuename -eq $defaultName)
}
# Sent only when present: a null is "not known", and an empty string would
# read as a driver or a port genuinely named nothing.
if ($queue.drivername) { $row['drivername'] = $queue.drivername }
if ($queue.portname) { $row['portname'] = $queue.portname }
if ($portAddress) { $row['portaddress'] = $portAddress }
$reported += $row
Log ("queue: {0} | driver={1} | port={2} | address={3} | default={4}" -f `
$queue.queuename, $queue.drivername, $queue.portname, $portAddress, $row['isdefault'])
}
Log "reporting $($reported.Count) queue(s), $skipped virtual queue(s) skipped"
if ($reported.Count -eq 0) {
# Legitimate and meaningful: it clears this host's observed rows so the
# comparison shows every assigned printer as missing, which is exactly what
# a bay with no queues is.
Log 'no real queues on this host; reporting an empty set (clears observed state)'
}
# Collector schema fields (lowercase concatenated). hostname is the identity
# field. observedat is sent for the record and named to match the declared
# collector schema; the server stamps its own and ignores this one.
$body = @{
hostname = $Hostname
queues = @($reported)
observedat = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss')
}
# Depth 4 covers hostname -> queues -> row -> value; the default of 2 flattens
# the rows to type names.
$json = $body | ConvertTo-Json -Compress -Depth 4
if ($WhatIfOnly) {
Log "WOULD POST $ApiUrl $json"
exit 0
}
Log ("POST {0} host={1} queues={2}" -f $ApiUrl, $Hostname, $reported.Count)
try {
$response = Invoke-RestMethod -Uri $ApiUrl -Method Post -Body $json `
-ContentType 'application/json' `
-Headers @{ 'X-API-Key' = $ApiKey } `
-TimeoutSec $TimeoutSec -ErrorAction Stop
Log ("RESPONSE {0}" -f ($response | ConvertTo-Json -Compress -Depth 4))
} catch {
Log "ERROR POST failed: $($_.Exception.Message)"
}
exit 0

155
plugins/printers/client/Set-ShopdbPrinters.ps1
View File

@@ -24,6 +24,12 @@
# logged-on person, so it records the desired default in HKLM and leaves applying
# it to a logon task. Without that, SYSTEM would set a default nobody sees.
#
# IT ALSO REGISTERS THAT LOGON TASK, and stages a LOCAL copy of
# Apply-ShopdbDefaultPrinter.ps1 for it to run. Recording a default that nothing
# ever applies was the gap: the queues appeared, the default never moved. The
# local copy is not tidiness - the share this script runs from is mounted only
# for the enforcement cycle, and the task fires at logon when it is gone.
#
# Exits 0 always: a printer problem must not fail an enforcement run.
param(
@@ -36,6 +42,26 @@ param(
[int]$TimeoutSec = 30,
# Where the per-user logon script is staged. Anywhere is fine as long as it
# is on this PC and every user can read it.
[string]$LocalScriptDir = (Join-Path ([Environment]::GetFolderPath('CommonApplicationData')) 'ShopDB'),
[string]$LogonTaskName = 'ShopDB default printer',
# The task runs as a GROUP, not a person: a shared bay has no one owner and
# the default must be applied for whoever logs on. If this name does not
# resolve - it is localised on non-English Windows - the well-known SID is
# tried instead.
[string]$UsersGroup = 'BUILTIN\Users',
# 0 means at logon only. A shared bay where people pick their own default
# can be pulled back on a repeat; a single-user PC should not be, so the
# neutral default is the one that does not argue with the user.
[int]$RepeatMinutes = 0,
# For a site that deploys the logon task by GPO instead.
[switch]$NoLogonTask,
# Report what would change and touch nothing.
[switch]$WhatIfOnly
)
@@ -53,6 +79,127 @@ function Log([string]$msg) {
"$ts $msg" | Tee-Object -FilePath $logFile -Append | Out-Null
}
# Resolved once, at script scope: $PSScriptRoot is empty when the file is piped
# into powershell rather than run by path, and the logon script sits beside this
# one.
$SCRIPTDIR = $PSScriptRoot
if (-not $SCRIPTDIR -and $MyInvocation.MyCommand.Path) {
$SCRIPTDIR = Split-Path -Parent $MyInvocation.MyCommand.Path
}
function Ensure-LogonTask {
# Half of this feature is per-user state that SYSTEM cannot write. All SYSTEM
# can do is arrange for something to run AS the user later, which is this
# task. Nothing else registered it, so the default was recorded every cycle
# and applied never.
if ($NoLogonTask) {
Log 'logon task: skipped (-NoLogonTask)'
return
}
$source = ''
if ($SCRIPTDIR) { $source = Join-Path $SCRIPTDIR 'Apply-ShopdbDefaultPrinter.ps1' }
if (-not $source -or -not (Test-Path $source)) {
Log "SKIP logon task: Apply-ShopdbDefaultPrinter.ps1 is not beside this script"
return
}
# THE LOCAL COPY IS LOAD-BEARING. This script runs from a share that is
# mounted only for the enforcement cycle; the task fires at logon, when the
# share is gone. A task pointing at the share never runs and says nothing.
$localscript = Join-Path $LocalScriptDir 'Apply-ShopdbDefaultPrinter.ps1'
$refreshed = $false
try {
if (-not (Test-Path $LocalScriptDir)) {
# Inherited ACL is what is wanted here: every user can read it, only
# admins can write it, so the task cannot be pointed somewhere else.
New-Item -ItemType Directory -Path $LocalScriptDir -Force -ErrorAction Stop | Out-Null
}
$stale = $true
if (Test-Path $localscript) {
$stale = (Get-FileHash -Path $localscript -Algorithm SHA256).Hash -ne
(Get-FileHash -Path $source -Algorithm SHA256).Hash
}
if ($stale) {
if ($WhatIfOnly) {
Log "WOULD stage the logon script at $localscript"
} else {
Copy-Item -Path $source -Destination $localscript -Force -ErrorAction Stop
$refreshed = $true
Log "staged the logon script at $localscript"
}
}
} catch {
# No local copy means no task worth registering - a task pointing at a
# file that is not there is worse than no task, because it looks fine.
Log "ERROR staging ${localscript}: $($_.Exception.Message)"
return
}
$arguments = "-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$localscript`""
$task = Get-ScheduledTask -TaskName $LogonTaskName -ErrorAction SilentlyContinue
if ($task -and -not $refreshed) {
# Re-registering every cycle throws away the task's run history, which
# is the only evidence it ever fired. So it is replaced only when it
# points somewhere other than the local copy, or has no group principal
# - a task left behind running as one person applies one person's
# default. Matched on the PATH rather than the whole argument string
# because Task Scheduler is free to normalise quoting, and an exact
# compare would churn over a difference that changes nothing.
$registered = @($task.Actions)[0]
$pointslocal = $registered -and $registered.Arguments -and
$registered.Arguments.IndexOf($localscript, [StringComparison]::OrdinalIgnoreCase) -ge 0
if ($pointslocal -and $task.Principal.GroupId) {
Log "logon task present: $LogonTaskName"
return
}
}
if ($WhatIfOnly) {
Log "WOULD register the logon task: $LogonTaskName -> $localscript"
return
}
try {
$triggers = @(New-ScheduledTaskTrigger -AtLogOn)
if ($RepeatMinutes -gt 0) {
$triggers += New-ScheduledTaskTrigger -Once -At (Get-Date) `
-RepetitionInterval (New-TimeSpan -Minutes $RepeatMinutes)
}
$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument $arguments
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries `
-DontStopIfGoingOnBatteries -StartWhenAvailable
} catch {
# An SKU without the ScheduledTasks module is the likely reason. Nothing
# to register with, and still not a reason to fail the run.
Log "ERROR building the logon task: $($_.Exception.Message)"
return
}
# Limited, not Highest: setting your own default printer needs no elevation,
# and a task the whole Users group can trigger should not have any.
$candidates = @($UsersGroup)
if ($UsersGroup -ne 'S-1-5-32-545') { $candidates += 'S-1-5-32-545' }
$lasterror = 'no principal accepted'
foreach ($groupid in $candidates) {
try {
$principal = New-ScheduledTaskPrincipal -GroupId $groupid -RunLevel Limited -ErrorAction Stop
Register-ScheduledTask -TaskName $LogonTaskName -Action $action -Trigger $triggers `
-Principal $principal -Settings $settings -Force -ErrorAction Stop | Out-Null
Log "registered the logon task: $LogonTaskName as $groupid"
return
} catch {
$lasterror = $_.Exception.Message
}
}
# A missing logon task means the default is not applied. It does not mean the
# queues are wrong, so it is logged and the run carries on.
Log "ERROR registering ${LogonTaskName}: $lasterror"
}
$REGPATH = 'HKLM:\SOFTWARE\GE\ShopDB'
if (-not $BaseUrl) {
@@ -72,6 +219,11 @@ if (-not $BaseUrl) {
Log "=== Set printers for $Hostname ==="
# Before the API call on purpose: the task depends on files on this PC, not on
# the server. A bad minute from the API must not leave a bay with no way to apply
# the default it was already told about.
Ensure-LogonTask
$url = $BaseUrl.TrimEnd('/') + '/api/printers/for-host/' + [uri]::EscapeDataString($Hostname)
try {
$response = Invoke-RestMethod -Uri $url -Method Get -TimeoutSec $TimeoutSec
@@ -206,7 +358,8 @@ foreach ($printer in $wanted) {
}
# The default is recorded, not applied: this process is SYSTEM and the setting
# is per user. Apply-ShopdbDefaultPrinter.ps1 reads it at logon.
# is per user. The logon task registered above runs
# Apply-ShopdbDefaultPrinter.ps1, which reads this value in the user's context.
if ($defaultname) {
if ($WhatIfOnly) {
Log "WOULD record default: $defaultname"

85
plugins/printers/migrations/versions/0005_observedqueues.py Normal file
View File

@@ -0,0 +1,85 @@
"""printers: printerobservedqueues table (what a bay reported it HAS).
ShopDB already knows what a bay SHOULD have (usesprinter/defaultprinter rows on
the machine). This table holds the other half: the queues a PC reported through
POST /api/collector/printers. Observed and assigned stay in separate tables on
purpose, so observed drift can never be mistaken for desired state.
One row per observed queue; the latest report for a host replaces all of that
host's rows. The unique index on (hostname, queuename) is the guard that turns a
half-finished replace into an IntegrityError instead of duplicate queues.
Explicit ops rather than create_plugin_tables: the helper builds a per-plugin
MetaData filtered to the plugin's own tables, so the foreign key to the core
assets table cannot resolve at CreateTable-compile time. Same reason the backups
baseline spells its ops out.
Guarded both ways, so a re-run (or a database where db.create_all already built
the table) is a no-op.
Revision ID: printers0005observedqueues
Revises: printers0004drivervendor
"""
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision = 'printers0005observedqueues'
down_revision = 'printers0004drivervendor'
branch_labels = None
depends_on = None
def upgrade():
bind = op.get_bind()
inspector = sa.inspect(bind)
if 'printerobservedqueues' in inspector.get_table_names():
return
op.create_table(
'printerobservedqueues',
sa.Column('printerobservedqueueid', sa.Integer(), nullable=False),
# Nullable and no index of its own beyond the explicit one below: an
# unenrolled bay still gets to report, and hostname is what identifies
# the report.
sa.Column('assetid', sa.Integer(), nullable=True),
sa.Column('hostname', sa.String(length=255), nullable=False),
sa.Column('queuename', sa.String(length=255), nullable=False),
sa.Column('drivername', sa.String(length=255), nullable=True),
sa.Column('portname', sa.String(length=255), nullable=True),
sa.Column('portaddress', sa.String(length=255), nullable=True),
sa.Column('isdefault', sa.Boolean(), nullable=False,
server_default=sa.false()),
sa.Column('isshared', sa.Boolean(), nullable=False,
server_default=sa.false()),
sa.Column('observedat', sa.DateTime(), nullable=False),
sa.Column('createddate', sa.DateTime(), nullable=False),
sa.Column('modifieddate', sa.DateTime(), nullable=False),
sa.Column('isactive', sa.Boolean(), nullable=False,
server_default=sa.true()),
sa.ForeignKeyConstraint(['assetid'], ['assets.assetid'],
ondelete='CASCADE'),
sa.PrimaryKeyConstraint('printerobservedqueueid'),
# Doubles as the read index for the hostname filter (leftmost column),
# so no separate hostname index is created.
sa.UniqueConstraint('hostname', 'queuename',
name='uq_printerobservedqueue_host_queue'),
)
# Port address is the primary match key from an observed queue back to a
# printer asset, so every comparison read hits it.
op.create_index('idx_printerobservedqueues_portaddress',
'printerobservedqueues', ['portaddress'])
op.create_index('idx_printerobservedqueues_assetid',
'printerobservedqueues', ['assetid'])
def downgrade():
bind = op.get_bind()
inspector = sa.inspect(bind)
if 'printerobservedqueues' not in inspector.get_table_names():
return
op.drop_index('idx_printerobservedqueues_assetid',
table_name='printerobservedqueues')
op.drop_index('idx_printerobservedqueues_portaddress',
table_name='printerobservedqueues')
op.drop_table('printerobservedqueues')

2
plugins/printers/models/__init__.py
View File

@@ -9,6 +9,7 @@ from .model_supply import ( # data-driven model -> toner/drum/waste mapping
CAPACITY_TIERS,
)
from .supply_alert import PrinterSupplyAlert # per-printer toner alert state
from .printer_observation import PrinterObservedQueue # observed queues per bay
__all__ = [
'Printer',
@@ -16,6 +17,7 @@ __all__ = [
'PrinterDriver',
'ModelSupply',
'PrinterSupplyAlert',
'PrinterObservedQueue',
'SUPPLY_TYPES',
'SUPPLY_COLORS',
'CAPACITY_TIERS',

109
plugins/printers/models/printer_observation.py Normal file
View File

@@ -0,0 +1,109 @@
"""What a bay actually HAS: one row per printer queue a PC reported.
This is the observed half of the printer loop. The assigned half already exists
as usesprinter/defaultprinter relationship rows on the machine, and the two are
kept apart on purpose: the moment a drifted bay's observed state is allowed to
write assignment rows, enforcement stops meaning anything. Nothing in this table
is desired state, and no code may promote it to desired state without a person
asking for that explicitly.
Current state, not history. The latest report for a host REPLACES every row that
host had before, so "what does this bay have" is a plain filter and never a
question about time. An append-only table would grow with every GE-Enforce cycle
and answer that question wrong. The audit log already records each ingest, which
is where the history lives.
Rows are keyed by hostname as reported, with assetid as a resolved convenience:
a bay can report before anyone creates its computer record, and the report must
still land. Matching an observed queue back to a ShopDB printer asset happens at
READ time (port address first, then queue name) so a printer added tomorrow
matches without the bay re-reporting.
Replacement is a hard DELETE of the host's rows, not a soft one: the inherited
isactive flag is not a soft-delete marker here, because a queue that is gone
from the bay is not observed state that has been retired, it is state that was
never observed again.
"""
from shopdb.api import db, BaseModel
class PrinterObservedQueue(BaseModel):
"""One Windows print queue seen on one reporting PC at one point in time."""
__tablename__ = 'printerobservedqueues'
printerobservedqueueid = db.Column(db.Integer, primary_key=True)
# The reporting PC, resolved at ingest. Nullable because an unenrolled bay
# still gets to report, and no backref: core assets must not grow a
# dependency on this plugin.
assetid = db.Column(
db.Integer,
db.ForeignKey('assets.assetid', ondelete='CASCADE'),
nullable=True,
comment='Reporting PC asset, resolved from hostname at ingest',
)
asset = db.relationship('Asset', lazy='select', viewonly=True)
# Authoritative identity of the report, stored as sent. assetid can be null
# or can go stale after a rename; hostname is what the replace keys on.
hostname = db.Column(
db.String(255),
nullable=False,
comment='Reporting PC hostname, as sent by the collector',
)
queuename = db.Column(
db.String(255),
nullable=False,
comment='Windows printer (queue) name',
)
drivername = db.Column(
db.String(255),
comment='Windows driver name, verbatim; comparable to printerdrivers.drivername',
)
portname = db.Column(
db.String(255),
comment='Windows port name, freeform',
)
# Primary match key: an IP or FQDN identifies a device unambiguously, where
# a queue name is only ever a convention. Null for non-TCP/IP ports.
portaddress = db.Column(
db.String(255),
comment='Host address the port points at (IP or FQDN)',
)
isdefault = db.Column(
db.Boolean,
nullable=False,
default=False,
comment='Was the default queue for the reporting context',
)
isshared = db.Column(
db.Boolean,
nullable=False,
default=False,
comment='Queue is shared off this PC',
)
# Server-stamped once per report, so every row of one report carries the
# same value and "when did this bay last report" needs no aggregate.
observedat = db.Column(
db.DateTime,
nullable=False,
comment='When the report that produced this row was ingested',
)
__table_args__ = (
# Windows queue names are unique per host, so this doubles as the read
# index for the hostname filter and turns a botched partial replace into
# an IntegrityError instead of silent duplicate queues.
db.UniqueConstraint('hostname', 'queuename',
name='uq_printerobservedqueue_host_queue'),
db.Index('idx_printerobservedqueues_portaddress', 'portaddress'),
db.Index('idx_printerobservedqueues_assetid', 'assetid'),
)
def __repr__(self):
return f"<PrinterObservedQueue {self.hostname}:{self.queuename}>"

328
plugins/printers/plugin.py
View File

@@ -3,6 +3,8 @@
import json
import logging
from pathlib import Path
import re
from typing import List, Dict, Optional, Type
from flask import Flask, Blueprint
@@ -12,13 +14,49 @@ from shopdb.plugins.base import BasePlugin, PluginMeta
from shopdb.api import db, AssetType
from .models import (
Printer, PrinterType, ModelSupply, PrinterDriver, PrinterSupplyAlert
Printer, PrinterType, ModelSupply, PrinterDriver, PrinterSupplyAlert,
PrinterObservedQueue
)
from .api import printers_asset_bp
from .services import ZabbixService
logger = logging.getLogger(__name__)
# Widths of the text columns on printerobservedqueues. A Windows queue name
# tops out well below this, but a report is unattended machine input: one
# oversized string must not turn into a 500 the bay retries every cycle.
OBSERVEDTEXTLIMIT = 255
def _observed_text(value, fieldname, warnings):
"""Trim one reported string to what the column holds, or None if blank."""
if value is None:
return None
text = str(value).strip()
if not text:
return None
if len(text) > OBSERVEDTEXTLIMIT:
warnings.append('truncated {} longer than {} characters'.format(
fieldname, OBSERVEDTEXTLIMIT))
text = text[:OBSERVEDTEXTLIMIT]
return text
def _observed_bool(value):
"""Coerce a reported flag to bool.
PowerShell's ConvertTo-Json emits real booleans, but hand-built payloads
and older clients send 'True'/'true'/1, and a bare truthiness test would
read the string 'False' as a default printer.
"""
if isinstance(value, bool):
return value
if isinstance(value, (int, float)):
return bool(value)
if isinstance(value, str):
return value.strip().lower() in ('true', '1', 'yes')
return False
class PrintersPlugin(BasePlugin):
"""
@@ -79,6 +117,7 @@ class PrintersPlugin(BasePlugin):
PrinterDriver, # driver links (SMB/HTTP)
ModelSupply, # model -> toner/drum/waste part numbers
PrinterSupplyAlert, # per-printer toner alert crossing state
PrinterObservedQueue, # what a bay reports it ACTUALLY has
]
def get_services(self) -> Dict[str, Type]:
@@ -109,11 +148,16 @@ class PrintersPlugin(BasePlugin):
logger.info("Printers plugin installed")
def get_settings_defaults(self) -> List[dict]:
"""Low-toner alert settings.
"""Low-toner alert settings plus the dashboard threshold.
The framework seeds these at install, at enable, and on every
`flask plugin upgrade-all`, so a key added in a later version reaches a
site that installed an earlier one.
ONE definition only. There were two, and the later one shadowed this
list outright: every alert setting below was silently never declared,
so the alerts settings page wrote keys the plugin did not own and a new
site seeded none of them. Add keys here; do not add a second method.
"""
return [
{
@@ -164,6 +208,16 @@ class PrintersPlugin(BasePlugin):
'description': 'Toner percent remaining at or below which a '
'critical email fires',
},
{
'key': 'printers_dashboardpercent',
'value': '5',
'valuetype': 'integer',
'category': 'printers',
'description': 'Supply percentage at or below which a printer '
'appears on the dashboard. Tighter than the '
'low-supplies report, which is for planning an '
'order rather than walking out to change one.',
},
]
def _ensure_asset_type(self) -> None:
@@ -286,21 +340,6 @@ class PrintersPlugin(BasePlugin):
return [printerscli]
def get_settings_defaults(self) -> List[Dict]:
"""Settings this plugin owns for the dashboard card."""
return [
{
'key': 'printers_dashboardpercent',
'value': '5',
'valuetype': 'integer',
'category': 'printers',
'description': 'Supply percentage at or below which a printer '
'appears on the dashboard. Tighter than the '
'low-supplies report, which is for planning an '
'order rather than walking out to change one.',
},
]
def get_dashboard_widgets(self) -> List[Dict]:
"""Dashboard card: printers needing a cartridge.
@@ -379,3 +418,258 @@ class PrintersPlugin(BasePlugin):
('printers.edit', 'Edit printers', 'printers'),
('printers.delete', 'Delete printers', 'printers'),
]
# ---- ADR-006 collector contract -------------------------------------
def get_collector_schema(self) -> Optional[dict]:
"""What a bay reports it ACTUALLY has (POST /api/collector/printers).
The observed half of the printer story. ShopDB already knows what a
host SHOULD have (/api/printers/for-host); this is what enumerating the
host found, kept apart from the assignment so drift stays visible.
Declaring this schema is what registers the endpoint - the dispatcher
in shopdb/core/api/collector.py discovers it, and brings the collector
key / managed-token auth and the audit row with it.
"""
return {
'identityfield': 'hostname',
'fields': {
'type': 'object',
'required': ['hostname', 'queues'],
'properties': {
'hostname': {
'type': 'string',
'description': 'Reporting PC (COMPUTERNAME or its '
'FQDN). The identity of the report: '
'the PC asset is resolved from it, but '
'the rows are keyed by the name, so an '
'unenrolled bay still reports.',
},
'queues': {
'type': 'array',
'description': "Every real print queue on the host. "
"This REPLACES the host's previous set, "
"so an empty array is a valid report "
"that clears it. A client whose "
"enumeration FAILED must send nothing "
"at all - never an empty array.",
'items': {
'type': 'object',
'required': ['queuename'],
'properties': {
'queuename': {
'type': 'string',
'description': 'Windows printer name.',
},
'drivername': {
'type': 'string',
'description': 'Driver name verbatim, as '
'the INF spells it.',
},
'portname': {
'type': 'string',
'description': 'Windows port name.',
},
'portaddress': {
'type': 'string',
'description': 'PrinterHostAddress of a '
'TCP/IP port - an IP or '
'FQDN. The primary key for '
'matching this queue to a '
'printer asset; omit it for '
'a non-TCP port.',
},
'isdefault': {
'type': 'boolean',
'description': 'True on the one queue that '
'is the default printer.',
},
'isshared': {
'type': 'boolean',
'description': 'True when the queue is '
'shared off this PC.',
},
},
},
},
'observedat': {
'type': 'string',
'format': 'date-time',
'description': 'Accepted and ignored. The server stamps '
'observedat at ingest, so a bay with a '
'wrong clock cannot report itself fresh '
'or stale.',
},
},
},
}
def apply_collector_payload(self, payload: dict) -> dict:
"""Replace one host's observed queue set (ADR-006).
THIS NEVER WRITES AN ASSIGNMENT. Observed and assigned are separate
tables on purpose: the moment a drifted bay's report is allowed to
become what that bay is told to install, enforcement stops meaning
anything.
Seeding an assignment from observed state is a human action through
PUT /api/printers/assignments/for-asset/<id>.
Replace, not append: this is current state, so the latest report is the
whole truth for that host. Nothing is matched to a printer asset here
either - resolution happens at read time, so a printer added to ShopDB
tomorrow matches yesterday's report without the bay reporting again.
"""
from datetime import datetime, timezone
warnings = []
hostname = (payload.get('hostname') or '').strip()
if not hostname:
raise ValueError('hostname is required')
queues = payload.get('queues')
if queues is None:
# Absent and empty are NOT the same thing. [] is a host that
# genuinely has no queues and clears its rows; a missing key is a
# malformed report, and treating it as a wipe would let one client
# bug erase the observed state of the fleet host by host.
raise ValueError('queues is required; send an empty array for a '
'host with no queues')
if not isinstance(queues, list):
raise ValueError('queues must be an array')
# One stamp for the whole report, so "when did this bay last report"
# reads off any row of it rather than a MAX over the set.
observedat = datetime.now(timezone.utc).replace(tzinfo=None)
# Resolved BEFORE the rows are written: assetid is a convenience for
# the read paths, and hostname stays the identity that the replace
# keys on, so an unresolved host still records everything it reported.
assetid = self._observed_assetid(hostname, warnings)
# Case-folded on both sides: one script sends COMPUTERNAME uppercase
# and another the lowercase FQDN, and MySQL forgives that while SQLite
# does not. Uncompared, the replace would leave the other spelling's
# rows in place and the host would appear to have every queue twice.
#
# A bulk delete so the DELETE reaches the database BEFORE the inserts
# below: a re-report repeats the same queue names, and the
# (hostname, queuename) unique index rejects the new rows if the old
# ones are still there. synchronize_session='fetch' costs one select
# and keeps the session's identity map honest, so a caller that read
# these rows earlier in the same request does not keep deleted ones.
# Every spelling of this host, not just the one it sent. The READ path
# treats a short name and its FQDN as the same machine, so a delete that
# matched only the exact string would leave the other spelling's rows
# behind and the host would appear to have every queue twice - the bug
# this replace exists to prevent. A PC that enrolls short and later
# reports fully qualified is normal, not exotic.
shortname = hostname.lower().split('.')[0]
predicate = db.or_(
db.func.lower(PrinterObservedQueue.hostname) == hostname.lower(),
db.func.lower(PrinterObservedQueue.hostname) == shortname)
if re.match(r'^[a-z0-9-]+$', shortname):
# Prefix match only for a plain name, as the read path does: a
# wildcard built from arbitrary input would delete another PC's rows.
predicate = db.or_(
predicate,
db.func.lower(PrinterObservedQueue.hostname).like(shortname + '.%'))
db.session.query(PrinterObservedQueue).filter(predicate).delete(
synchronize_session='fetch')
seennames = set()
defaultqueue = None
stored = 0
for entry in queues:
if not isinstance(entry, dict):
warnings.append('ignored a queue entry that was not an object')
continue
queuename = _observed_text(entry.get('queuename'), 'queuename',
warnings)
if not queuename:
warnings.append('ignored a queue with no queuename')
continue
if queuename.lower() in seennames:
# Windows cannot hold two queues of one name on a host, so this
# is a doubled line in the report. Dropping it keeps the
# (hostname, queuename) unique index from failing the whole
# report over one bad row.
warnings.append(
'ignored duplicate queue {!r}'.format(queuename))
continue
seennames.add(queuename.lower())
isdefault = _observed_bool(entry.get('isdefault'))
if isdefault and defaultqueue is not None:
# A host has exactly one default printer. Two means the client
# misread it, and keeping both would leave the seed candidate
# picking one at random.
warnings.append(
'more than one queue reported as default; kept {!r}'.format(
defaultqueue))
isdefault = False
if isdefault:
defaultqueue = queuename
db.session.add(PrinterObservedQueue(
hostname=hostname,
queuename=queuename,
drivername=_observed_text(entry.get('drivername'), 'drivername',
warnings),
portname=_observed_text(entry.get('portname'), 'portname',
warnings),
portaddress=_observed_text(entry.get('portaddress'),
'portaddress', warnings),
isdefault=isdefault,
isshared=_observed_bool(entry.get('isshared')),
assetid=assetid,
observedat=observedat,
))
stored += 1
# flush, not commit: the collector dispatcher owns the transaction and
# commits after writing its AuditLog row. Committing here would leave
# an unaudited report behind if that write then failed.
db.session.flush()
# Always 'updated'. This endpoint replaces observed rows and creates no
# asset, so 'created' never applies, and calling an identical re-report
# 'noop' would hide that the bay is still checking in.
return {
'action': 'updated',
'assetid': assetid,
'warnings': warnings,
'extra': {'queuecount': stored},
}
def _observed_assetid(self, hostname, warnings):
"""Computer asset this hostname belongs to, or None with a warning.
Reuses the resolver behind /api/printers/for-host rather than repeating
it: if the two ever disagreed, a bay would be compared against the
assignment of a different PC than the one it was told to install from.
An unknown hostname is a WARNING, not an error. A bay reporting before
its PC record exists is normal on a new build, the rows are keyed by
hostname and resolve the moment that record appears, and a 500 here
would make the client retry and log a failure on every cycle forever.
"""
try:
from .api.asset_routes import _computer_by_hostname
row = _computer_by_hostname(hostname)
except ImportError:
# A lean site can run without the computers plugin (ADR-013). The
# observed rows are still worth keeping - they just stay unresolved.
warnings.append('computers plugin not installed; observed queues '
'stored against the hostname only')
return None
if row is None:
warnings.append(
'hostname {!r} does not match a known PC; observed queues '
'stored unresolved'.format(hostname))
return None
# _computer_by_hostname returns the (Computer, Asset) pair.
return row[1].assetid