99"""
1010import collections .abc
1111import enum
12+ import threading
1213from typing import TYPE_CHECKING , cast , overload
1314
1415import 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