Skip to content

Commit 87dae59

Browse files
committed
fix(registry): unregistering a custom protocol removes its name from __proto__ (#1505)
- The nine code registrars (register_linktype, register_pcap, register_pcapng, register_ethertype, register_transtype, register_apptype, register_tcp, register_udp, register_sctp) end in a new _register_name: register_protocol, plus a lease on the by-name entry when the write changed it, recording what it displaced and which (destination, code) pairs still hold it. - Leases stack per name, one per write, so a class can hold two (a built-in retaking its name from a custom shadow). Releasing the top one restores what it displaced; releasing a buried one hands that to the lease above. A name held before the registration is never leased, so no restore removes it. - The lease tables are guarded by a module RLock. - Delete the Gap(1505) rows; add test_registry_name_restore_unit.py, with a seeded fuzz checked after every call.
1 parent 81efa60 commit 87dae59

3 files changed

Lines changed: 453 additions & 20 deletions

File tree

‎pcapkit/foundation/registry/protocols.py‎

Lines changed: 173 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
"""
1010
import collections.abc
1111
import enum
12+
import threading
1213
from typing import TYPE_CHECKING, cast, overload
1314

1415
import aenum
@@ -169,8 +170,9 @@ def register_protocol(protocol: 'Type[ProtocolBase]') -> 'None':
169170
presence alone is not enough. This registry's key is *derived* from the
170171
class rather than supplied by a caller, and this function is the funnel
171172
every wrapper registrar calls -- :func:`register_tcp`, :func:`register_udp`,
172-
:func:`register_apptype`, :func:`register_linktype` and the rest all end in
173-
``register_protocol(module)``. So registering one class under two codes, a
173+
:func:`register_apptype`, :func:`register_linktype` and the rest all end by
174+
calling it with their class, and registering their code back undoes that
175+
call's write (:issue:`1505`). So registering one class under two codes, a
174176
supported and documented thing to do, reaches this function twice with the
175177
same class and nothing at stake; a presence-only guard would warn about an
176178
overwrite that overwrote nothing. Warning on the harmless case is not free:
@@ -236,6 +238,164 @@ class rather than supplied by a caller, and this function is the funnel
236238
logger.debug('registered protocol: %s', protocol.__name__)
237239

238240

241+
#: Sentinel for a name :data:`pcapkit.protocols.__proto__` did not hold.
242+
_MISSING = object()
243+
244+
245+
class _NameLease:
246+
"""A :data:`pcapkit.protocols.__proto__` entry a code registration put there.
247+
248+
Each code registrar below ends by naming its class in the by-name registry,
249+
and :mod:`pcapkit.foundation.registry` has no ``unregister``: a code is
250+
undone by registering the entry it displaced (:issue:`1363`). Without a
251+
record of that by-name write, handing a code back restored the code and left
252+
the name behind (:issue:`1505`). A lease records what the write displaced and
253+
which codes still dispatch to the class, so the last of them to be handed
254+
back puts the displaced entry back, or removes the name if it was new.
255+
256+
A lease is one write, not one class: the same class can hold two leases on
257+
a name -- e.g. a built-in registered at one port over a custom class
258+
shadowing it at another -- and each undoes only its own write.
259+
260+
"""
261+
262+
__slots__ = ('name', 'protocol', 'displaced', 'codes')
263+
264+
def __init__(self, name: 'str', protocol: 'Type[ProtocolBase]', displaced: 'Any') -> 'None':
265+
#: The key written in :data:`pcapkit.protocols.__proto__`.
266+
self.name = name
267+
#: The class written under it.
268+
self.protocol = protocol
269+
#: The entry it displaced, or :data:`_MISSING` for a new name.
270+
self.displaced = displaced
271+
#: ``(destination, code)`` registrations still holding the lease.
272+
self.codes = set() # type: set[tuple[type, Any]]
273+
274+
275+
#: Name -> its leases, oldest first. Each lease displaced the one below it,
276+
#: unless the name was written by other means in between; the last is the one
277+
#: a lookup sees, unless the name has been written since.
278+
_NAME_LEASES = {} # type: dict[str, list[_NameLease]]
279+
#: ``(destination, code)`` -> the lease its registration holds.
280+
_CODE_LEASES = {} # type: dict[tuple[type, Any], _NameLease]
281+
#: Serialises the two tables above, so concurrent registrars cannot tear them.
282+
_LEASE_LOCK = threading.RLock()
283+
284+
285+
def _fold_lease(stack: 'list[_NameLease]', index: 'int') -> 'None':
286+
"""Retire ``stack[index]``, a lease now displacing its own class.
287+
288+
That happens once the lease between it and an earlier write of the same
289+
class is handed back, e.g. a custom ``IPv4`` released from under the
290+
built-in ``IPv4`` registered over it. Undoing it would change nothing, so
291+
its codes move to the lease below when that is the same class, and
292+
otherwise -- the class was named by other means -- hold nothing.
293+
294+
Args:
295+
stack: The name's leases, oldest first.
296+
index: Position of the lease to retire.
297+
298+
"""
299+
lease = stack.pop(index)
300+
below = stack[index - 1] if index > 0 else None
301+
if below is not None and below.protocol is not lease.protocol:
302+
below = None
303+
for target in lease.codes:
304+
if _CODE_LEASES.get(target) is not lease:
305+
continue
306+
if below is None:
307+
del _CODE_LEASES[target]
308+
else:
309+
below.codes.add(target)
310+
_CODE_LEASES[target] = below
311+
312+
313+
def _release_name(target: 'tuple[type, Any]') -> 'None':
314+
"""Hand back the lease ``target``'s registration held.
315+
316+
Once no code holds the lease, it leaves its name's stack. On top, it puts
317+
the name back to the entry it displaced, or removes a new name -- unless the
318+
name was written by other means since, in which case that write stands.
319+
Buried, it hands what it displaced to the lease above, if that lease
320+
displaced it.
321+
322+
Args:
323+
target: The ``(destination, code)`` being registered over.
324+
325+
"""
326+
lease = _CODE_LEASES.pop(target, None)
327+
if lease is None:
328+
return
329+
lease.codes.discard(target)
330+
if lease.codes:
331+
return
332+
333+
stack = _NAME_LEASES.get(lease.name, [])
334+
index = next((i for i, item in enumerate(stack) if item is lease), None)
335+
if index is None:
336+
return
337+
del stack[index]
338+
if index < len(stack):
339+
above = stack[index]
340+
if above.displaced is lease.protocol:
341+
above.displaced = lease.displaced
342+
if above.displaced is above.protocol:
343+
_fold_lease(stack, index)
344+
elif protocol_registry.get(lease.name) is lease.protocol:
345+
if lease.displaced is _MISSING:
346+
protocol_registry.pop(lease.name, None)
347+
else:
348+
protocol_registry[lease.name] = lease.displaced
349+
logger.debug('released protocol: %s', lease.protocol.__name__)
350+
if not stack:
351+
_NAME_LEASES.pop(lease.name, None)
352+
353+
354+
def _register_name(protocol: 'Type[ProtocolBase]', *targets: 'tuple[type, Any]') -> 'None':
355+
"""Name ``protocol`` in :data:`pcapkit.protocols.__proto__` for ``targets``.
356+
357+
The tail of every code registrar: :func:`register_protocol`, preceded by
358+
releasing whatever each target code held before, and followed by a lease
359+
when the write changed the name, so that registering the code back undoes
360+
it (:issue:`1505`). A name already showing ``protocol`` -- shipped, defined
361+
by a :class:`~pcapkit.protocols.protocol.Protocol` subclass, or registered
362+
directly -- is not leased, so no restore takes it away; one showing it
363+
through a lease extends that lease to ``targets``.
364+
365+
Args:
366+
protocol: Protocol class just registered -- and so validated -- at ``targets``.
367+
*targets: The ``(destination, code)`` pairs it was registered at.
368+
369+
"""
370+
name = protocol.__name__.upper()
371+
with _LEASE_LOCK:
372+
stack = _NAME_LEASES.get(name)
373+
if stack and stack[-1].protocol is protocol and protocol_registry.get(name) is protocol:
374+
current = stack[-1] # type: Optional[_NameLease]
375+
else:
376+
current = None
377+
for target in targets:
378+
if current is None or _CODE_LEASES.get(target) is not current:
379+
_release_name(target)
380+
381+
incumbent = protocol_registry.get(name, _MISSING)
382+
register_protocol(protocol)
383+
if protocol_registry.get(name) is not protocol:
384+
return
385+
386+
stack = _NAME_LEASES.get(name)
387+
if incumbent is not protocol:
388+
lease = _NameLease(name, protocol, incumbent)
389+
_NAME_LEASES.setdefault(name, []).append(lease)
390+
elif stack and stack[-1].protocol is protocol:
391+
lease = stack[-1]
392+
else:
393+
return
394+
lease.codes.update(targets)
395+
for target in targets:
396+
_CODE_LEASES[target] = lease
397+
398+
239399
#: Enum type -> the class(es) owning the :attr:`ProtocolBase.__proto__
240400
#: <pcapkit.protocols.protocol.ProtocolBase.__proto__>` dispatch registry
241401
#: keyed by that enum type -- the "registry-of-registries" that lets
@@ -413,7 +573,7 @@ def register_linktype(code: 'LinkType', module: 'str | ModuleDescriptor[Protocol
413573
# register protocol to protocol registry
414574
if isinstance(module, ModuleDescriptor):
415575
module = module.klass
416-
register_protocol(module)
576+
_register_name(module, (Frame, code), (PCAPNG, code))
417577

418578

419579
@overload
@@ -450,7 +610,7 @@ def register_pcap(code: 'LinkType', module: 'str | ModuleDescriptor[ProtocolBase
450610
# register protocol to protocol registry
451611
if isinstance(module, ModuleDescriptor):
452612
module = module.klass
453-
register_protocol(module)
613+
_register_name(module, (Frame, code))
454614

455615

456616
@overload
@@ -487,7 +647,7 @@ def register_pcapng(code: 'LinkType', module: 'str | ModuleDescriptor[ProtocolBa
487647
# register protocol to protocol registry
488648
if isinstance(module, ModuleDescriptor):
489649
module = module.klass
490-
register_protocol(module)
650+
_register_name(module, (PCAPNG, code))
491651

492652

493653
###############################################################################
@@ -529,7 +689,7 @@ def register_ethertype(code: 'EtherType', module: 'str | ModuleDescriptor[Protoc
529689
# register protocol to protocol registry
530690
if isinstance(module, ModuleDescriptor):
531691
module = module.klass
532-
register_protocol(module)
692+
_register_name(module, (Link, code))
533693

534694

535695
###############################################################################
@@ -571,7 +731,7 @@ def register_transtype(code: 'TransType', module: 'str | ModuleDescriptor[Protoc
571731
# register protocol to protocol registry
572732
if isinstance(module, ModuleDescriptor):
573733
module = module.klass
574-
register_protocol(module)
734+
_register_name(module, (Internet, code))
575735

576736

577737
# NOTE: pcapkit.protocols.internet.ipv4.IPv4.__option__
@@ -942,6 +1102,7 @@ def register_apptype(code: 'int | Enum_AppType', module: 'str | ModuleDescriptor
9421102
TransportProtocol.tcp: TCP,
9431103
TransportProtocol.udp: UDP,
9441104
})
1105+
targets = [] # type: list[tuple[type, Any]]
9451106
for proto in transport:
9461107
# NOTE: a composite is not a key here, so ``tcp | udp`` is rejected
9471108
# rather than quietly registering under both. Naming them one at a time
@@ -951,12 +1112,13 @@ def register_apptype(code: 'int | Enum_AppType', module: 'str | ModuleDescriptor
9511112
raise RegistryError(f'unknown transport protocol: {proto.name}')
9521113

9531114
cls.register(code, module)
1115+
targets.append((cls, code))
9541116
logger.debug('registered %s port: %s', proto.name, code)
9551117

9561118
# register protocol to protocol registry
9571119
if isinstance(module, ModuleDescriptor):
9581120
module = module.klass
959-
register_protocol(module)
1121+
_register_name(module, *targets)
9601122

9611123

9621124
@overload
@@ -995,7 +1157,7 @@ def register_tcp(code: 'int | Enum_AppType', module: 'str | ModuleDescriptor[Pro
9951157
# register protocol to protocol registry
9961158
if isinstance(module, ModuleDescriptor):
9971159
module = module.klass
998-
register_protocol(module)
1160+
_register_name(module, (TCP, code))
9991161

10001162

10011163
# NOTE: pcapkit.protocols.transport.tcp.TCP.__option__
@@ -1084,7 +1246,7 @@ def register_udp(code: 'int | Enum_AppType', module: 'str | ModuleDescriptor[Pro
10841246
# register protocol to protocol registry
10851247
if isinstance(module, ModuleDescriptor):
10861248
module = module.klass
1087-
register_protocol(module)
1249+
_register_name(module, (UDP, code))
10881250

10891251

10901252
@overload
@@ -1128,7 +1290,7 @@ def register_sctp(code: 'int | SCTP_PayloadProtocolIdentifier', module: 'str | M
11281290
# register protocol to protocol registry
11291291
if isinstance(module, ModuleDescriptor):
11301292
module = module.klass
1131-
register_protocol(module)
1293+
_register_name(module, (SCTP, code))
11321294

11331295

11341296
###############################################################################

0 commit comments

Comments
 (0)