From 4dd998ee80d840338411adadbf9e9b3e4f76bd07 Mon Sep 17 00:00:00 2001 From: Peter Silva Date: Thu, 24 Oct 2024 16:52:25 -0400 Subject: [PATCH 1/5] for #1267 suppress duplicate bindings --- sarracenia/config/subscription.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sarracenia/config/subscription.py b/sarracenia/config/subscription.py index 446023ed0..bd882181d 100755 --- a/sarracenia/config/subscription.py +++ b/sarracenia/config/subscription.py @@ -59,12 +59,12 @@ def add(self, new_subscription): for s in self: if ( s['broker'] == new_subscription['broker'] ) and \ ( s['queue']['name'] == new_subscription['queue']['name'] ): + newb = new_subscription['bindings'][0] for b in s['bindings']: - newb = new_subscription['bindings'][0] - if (b['sub'] != newb['sub']) or (b['prefix'] != newb['prefix']): - s['bindings'].append( { 'exchange': newb['exchange'], \ - 'prefix':newb['prefix'], 'sub':newb['sub'] } ) + if newb == b: found=True + if not found: + s['bindings'].append( newb ) if not found: self.append(new_subscription) From d6dc62cae02825effefeb16e4d7f86eb39418400 Mon Sep 17 00:00:00 2001 From: Peter Silva Date: Thu, 24 Oct 2024 23:50:04 -0400 Subject: [PATCH 2/5] #1267 document new importance of order of queueName vs. subtopic --- docs/source/How2Guides/UPGRADING.rst | 6 ++++- docs/source/Reference/sr3_options.7.rst | 32 ++++++++++++++++--------- 2 files changed, 26 insertions(+), 12 deletions(-) diff --git a/docs/source/How2Guides/UPGRADING.rst b/docs/source/How2Guides/UPGRADING.rst index 8004c41e7..b19e47aac 100644 --- a/docs/source/How2Guides/UPGRADING.rst +++ b/docs/source/How2Guides/UPGRADING.rst @@ -52,7 +52,11 @@ is perhaps complex. This version will read and write both files, so as to preserve ability to downgrade. later version will drop support for qname files. - +*CHANGE*: in configuration files: *subtopic* must come after +the relevant queue naming options (queueName, queueShare) +in prior releases, the queue naming was a global setting. +In a future version, one will be able to subscribe to multiple +queues with a single subscriber. 3.0.54 ------ diff --git a/docs/source/Reference/sr3_options.7.rst b/docs/source/Reference/sr3_options.7.rst index e04faf486..b5246dbfe 100644 --- a/docs/source/Reference/sr3_options.7.rst +++ b/docs/source/Reference/sr3_options.7.rst @@ -1549,6 +1549,9 @@ Instances started on any node with access to the same shared file will use the same queue. Some may want use the *queueName* option as a more explicit method of sharing work across multiple nodes. +This *subtopic* option should appear after the queueName setting in files +for the topic bindings to apply to the given queue. + queueShare ( default: ${USER}_${HOSTNAME}_${RAND8} ) ---------------------------------------------------------- @@ -1567,6 +1570,9 @@ will result in a random 8 digit number being appended to the queue name. All the instances within the configuration with access to the same state directory will use the queue name thus defined. +This *subtopic* option should appear after the queueShare setting in files +for the topic bindings to apply to the given queue. + randomize ---------------- @@ -1973,8 +1979,8 @@ message flows. subtopic (default: #) ------------------------------------ -Within an exchange's postings, the subtopic setting narrows the product selection. -To give a correct value to the subtopic, +Within an exchange's postings, the subtopic setting narrows the product selection, +for objects to place in the currently selected queue. To give a correct value to the subtopic, one has the choice of filtering using **subtopic** with only AMQP's limited wildcarding and length limited to 255 encoded bytes, or the more powerful regular expression based **accept/reject** mechanisms described below. The difference being that the @@ -1983,18 +1989,18 @@ to the client at all. The **accept/reject** patterns apply to messages sent by broker to the subscriber. In other words, **accept/reject** are client side filters, whereas **subtopic** is server side filtering. -It is best practice to use server side filtering to reduce the number of notification messages sent -to the client to a small superset of what is relevant, and perform only a fine-tuning with the -client side mechanisms, saving bandwidth and processing for all. +Use server side filtering to reduce the number of notification messages sent +to the client to a small superset of what is relevant, and refine further with the +client side accept/reject, saving bandwidth and processing for all. -topicPrefix is primarily of interest during protocol version transitions, -where one wishes to specify a non-default protocol version of messages to -subscribe to. +Often, the user specifies one exchange, and several subtopic options. +**Subtopic** is what is normally used to indicate messages of interest +for a given queue. If needed, queueName, and/or queueShare need to be +earlier in the configuration file for the subtopic to apply to the selected queue. -Usually, the user specifies one exchange, and several subtopic options. -**Subtopic** is what is normally used to indicate messages of interest. To use the subtopic to filter the products, match the subtopic string with -the relative path of the product. +the relative path of the product (non Sarracenia pumps may have different +topic hierarchy conventions.) For example, consuming from DD, to give a correct value to subtopic, one can browse the our website **http://dd.weather.gc.ca** and write down all directories @@ -2084,6 +2090,10 @@ Sarracenia has a convention for how topics for products should be organized. The a topicPrefix, followed by subtopics derived from the *relPath* field of the message. Some networks may choose to use different topic conventions, external to sarracenia. +topicPrefix is primarily of interest during protocol version transitions, +where one wishes to specify a non-default protocol version of messages to +subscribe to. + timeout (default: 0) ------------------------------- From 79345d2abecea5efd2cfa6351acc3b3ffc56f020 Mon Sep 17 00:00:00 2001 From: Peter Silva Date: Fri, 25 Oct 2024 08:48:07 -0400 Subject: [PATCH 3/5] #1267 translation, and touchup of documentation --- docs/source/Reference/sr3_options.7.rst | 13 +++++++---- docs/source/fr/CommentFaire/MiseANiveau.rst | 4 ++++ docs/source/fr/Reference/sr3_options.7.rst | 26 +++++++++++++++++---- 3 files changed, 33 insertions(+), 10 deletions(-) diff --git a/docs/source/Reference/sr3_options.7.rst b/docs/source/Reference/sr3_options.7.rst index b5246dbfe..85e608d51 100644 --- a/docs/source/Reference/sr3_options.7.rst +++ b/docs/source/Reference/sr3_options.7.rst @@ -2090,11 +2090,6 @@ Sarracenia has a convention for how topics for products should be organized. The a topicPrefix, followed by subtopics derived from the *relPath* field of the message. Some networks may choose to use different topic conventions, external to sarracenia. -topicPrefix is primarily of interest during protocol version transitions, -where one wishes to specify a non-default protocol version of messages to -subscribe to. - - timeout (default: 0) ------------------------------- @@ -2144,6 +2139,14 @@ prepended to the sub-topic to form a complete topic hierarchy. This option applies to subscription bindings. Denotes the version of messages received in the sub-topics. (v03 refers to ``_) +topicPrefix is primarily of interest during protocol version transitions, +where one wishes to specify a non-default protocol version of messages to +subscribe to. + +For example, Sr3 expects v03 messages by default, but there are +plenty of sources that offer the old version (requiring a topicPrefix of *v02.post*) +to specify the old version of messages. + users (default: false) ----------------------------- diff --git a/docs/source/fr/CommentFaire/MiseANiveau.rst b/docs/source/fr/CommentFaire/MiseANiveau.rst index d6de452d9..83e8e231e 100644 --- a/docs/source/fr/CommentFaire/MiseANiveau.rst +++ b/docs/source/fr/CommentFaire/MiseANiveau.rst @@ -51,6 +51,10 @@ est peut-être complexe. Cette version lira et écrira les deux fichiers, afin de préserver la possibilité de rétrogradation. La version ultérieure abandonnera la prise en charge des fichiers qname. +*CHANGEMENT* : dans les fichiers de configuration : *subtopic* doit venir après +la spécification de nom de file d'attente pertinentes (queueName, queueShare.) +Dans les versions précédentes, la dénomination de la file d'attente était un paramètre global. +Dans une future version, on pourra s'abonner à plusieurs files d'attente avec un seul abonné. 3.0.54 ------ diff --git a/docs/source/fr/Reference/sr3_options.7.rst b/docs/source/fr/Reference/sr3_options.7.rst index ab805a098..a52f5e0f5 100644 --- a/docs/source/fr/Reference/sr3_options.7.rst +++ b/docs/source/fr/Reference/sr3_options.7.rst @@ -1539,6 +1539,8 @@ Les instances démarrées sur n’importe quel nœud ayant accès au même fichi même fil d’attente. Certains voudront peut-être utiliser l’option *queueName* comme méthode plus explicite de partager le travail sur plusieurs nœuds. Il est pourtant recommandé d´utiliser queueShare a cette fin. +l´option *subtopic* devrait apparaître après le paramètre queueName dans les fichiers +pour que les liaisons de sujet s'appliquent à la file d'attente spécifié. queueShare (default: ${USER}_${HOSTNAME}_${RAND8} ) @@ -1558,6 +1560,8 @@ Ce entraînera l'ajout d'un nombre aléatoire à 8 chiffres au nom de la file d' Toutes les instances de la configuration ayant accès au même répertoire d'état utilisera le nom de file d'attente ainsi défini. +l´option *subtopic* devrait apparaître après le paramètre queueShare dans les fichiers +pour que les liaisons de sujet s'appliquent à la file d'attente spécifié. randomize ---------------- @@ -1965,7 +1969,8 @@ origine. À utiliser uniquement avec des flux de données fiables et organisés subtopic (défaut: #) ----------------------------------- -Dans les publications d’un échange, le paramètre de subtopic restreint la sélection du produit. +Dans les publications d’un échange, le paramètre de subtopic sert à préciser des messages +à placer dans la file d'attente actuellement sélectionnée. Pour donner la bonne valeur au subtopic, on a le choix de filtrer en utilisant **subtopic** seulement avec le wildcarding limité d’AMQP et une longueur limitée à 255 octets encodés, ou de manière plus puissante, les expressions régulière basés sur les mécanismes **accept/reject** décrits ci-dessous. La différence est que le @@ -1978,12 +1983,17 @@ Il est recommandé d’utiliser le filtrage côté serveur pour réduire le nomb au client et envoyer seulement ce qui est pertinent, et seulement régler les mécanismes côté client, économisant du bandwidth et du traitement pour tous. -topicPrefix est principalement utilisé lors des transitions de version de protocole, -où l’on souhaite spécifier une version de protocole non-commune des messages d'annonce auquel s’abonner. - -Normalement, l’utilisateur spécifie un échange et plusieurs options de subtopic. **subtopic** est ce qui est normalement utilisé pour indiquer les messages d'annonce d'intérêt. Pour utiliser **subtopic** pour filtrer les produits, + +Souvent, l'utilisateur spécifie un échange et plusieurs options de sous-thèmes. +Le **subtopic** est ce qui est normalement utilisé pour indiquer les messages d'intérêt +pour une file d'attente donnée. Si nécessaire, **queueName** et/ou **queueShare** +doivent apparaître plus tôt dans le fichier de configuration pour que le sous-thème +s'applique à la file d'attente sélectionnée. + il faut que la chaîne de caractère subtopic corresponde au chemin relatif du produit. +(les pompes non Sarracenia peuvent avoir d´autres conventions de hiérarchie des sujets.) + Par exemple, en consommant à partir de DD, pour donner la bonne valeur au subtopic, il est possible de parcourir le site Web **http://dd.weather.gc.ca** et noter tous les répertoires @@ -2109,6 +2119,12 @@ rajouté au subtopic pour former une hiérarchie complète de thèmes (topics). Cette option s’applique aux liaisons d’abonnement. Indique la version des messages d'annonce reçus dans les subtopics. (V03 fait référence à ``_) +topicPrefix sert principalement lors des transitions de format de messages. +Le topicPrefix identifie dans quel version de format les messages sous le thème +sont créés. Sr3 s´attend a des messages v03 par défault, mais il y plein +de sources qui offrent l´ancienne version (nécessitant une topicPrefix de *v02.post*) +pour spécifier l´ancienned version de messages. + topicCopy (défaut: False) ------------------------- From aa8a58d1106ec7146f035bd25d9a722ef1f89c26 Mon Sep 17 00:00:00 2001 From: Peter Silva Date: Fri, 25 Oct 2024 10:23:01 -0400 Subject: [PATCH 4/5] #1267 sr3 convert move queueName above subtopic --- sarracenia/sr.py | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/sarracenia/sr.py b/sarracenia/sr.py index 5215c44c0..6a3109364 100755 --- a/sarracenia/sr.py +++ b/sarracenia/sr.py @@ -2775,6 +2775,24 @@ def convert1(self,cfg): v3_cfg.write('#v2 sftp handling is always absolute, sr3 is relative. might need this, remove when all sr3:\n') v3_cfg.write('#flowcb accept.sftp_absolute\n') + queueName=None + + #1st prep pass (for cases when re-ordering needed.) + with open(v2_config_path, 'r') as v2_cfg: + for line in v2_cfg.readlines(): + if len(line.strip()) < 1: + continue + if line[0].startswith('#'): + continue + line = line.strip().split() + k = line[0] + if k in synonyms: + k = synonyms[k] + if k in [ 'queueName' ]: + queueName=line[1] + + #2nd re-write pass. + subtopicFound=False with open(v2_config_path, 'r') as v2_cfg: for line in v2_cfg.readlines(): if len(line.strip()) < 1: @@ -2818,7 +2836,13 @@ def convert1(self,cfg): else: logger.error( f"unknown checksum spec: {line}") continue - + elif k == 'queueName': + if subtopicFound or not queueName: + continue + elif k == 'subtopic': + if queueName: + v3_cfg.write(f'queueName {queueName}\n') + queueName=None if (k == 'accept') : if line[1] == '.*': accept_all_seen=True From b10f050049ce9e7eeb6fc14180b8519cc4feec1a Mon Sep 17 00:00:00 2001 From: Peter Silva Date: Fri, 25 Oct 2024 10:46:10 -0400 Subject: [PATCH 5/5] #1267 emit a warning about misplaced queueName vs. subtopic --- sarracenia/config/__init__.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/sarracenia/config/__init__.py b/sarracenia/config/__init__.py index d3ccd8b96..05f7fcffd 100755 --- a/sarracenia/config/__init__.py +++ b/sarracenia/config/__init__.py @@ -1536,6 +1536,8 @@ def parse_file(self, cfg, component=None): saved_lineno=0 self.files.append(cfgfilepath) + self.subtopic_seen=False + for l in open(cfgfilepath, "r").readlines(): lineno+=1 if self.lineno > 0: @@ -1646,6 +1648,7 @@ def parse_line(self, component, cfg, cfname, lineno, l ): logger.error( f"{','.join(self.files)}:{self.lineno} file {v} failed to parse: {ex}" ) logger.debug('Exception details: ', exc_info=True) elif k in ['subtopic']: + self.subtopic_seen=True self._parse_binding(v) elif k in ['topicPrefix']: if '/' in v : @@ -1753,6 +1756,12 @@ def parse_line(self, component, cfg, cfname, lineno, l ): logger.error( f'{",".join(self.files)}:{lineno} invalid entry {i} in {k}. Must be one of: {set_choices[k]}' ) elif k in str_options: + # queueName warning... is for something that is not an error... + # probably need to remove this warning later... because people could use default queue with subtopic and + # specify a second queue with different bindings... so this warning could be complaining about something + # that is correct. but in every current case, the warning will be helpful. + if ( k == 'queueName' ) and self.subtopic_seen: + logger.warning( f"queueName usually should be before subtopic in configs: subtopic to default queue" ) if ( k == 'directory' ) and not self.download: logger.info( f"{','.join(self.files)}:{lineno} if download is false, directory has no effect" )