Si vous avez un serveur Windows, vous pouvez également utiliser IIS pour configurer un reverse proxy vers Constellation.

Dans cet article nous allons découvrir comment exposer le serveur Constellation derrière un serveur Nginx protégé avec un certificat SSL Let’s Encrypt.

Prérequis : avoir une Constellation exposée publiquement avec un nom DNS

Avant de démarrer vous devez avoir un serveur Constellation opérationel.

Si vous installez Constellation sur un Linux, cela se résume à lancer la commande ci-dessous et à suivre l’assistant :

wget -O install.sh https://developer.myconstellation.io/download/installers/install-linux.sh && chmod +x install.sh && ./install.sh

Pour plus d’information, veuillez suivre le guide : Installer Constellation sur Linux.

On considéra à ce stade que votre serveur Constellation est démarré et opérationnel. Vous pouvez lancer la commande suivante pour vérifier le statut des services Constellation :

sudo supervisorctl status

Vous devriez voir le “constellation-server” avec le statut “RUNNING” (et la sentinelle si déployée) :

sebastien@ubuntu:~$ sudo supervisorctl status
constellation-sentinel           RUNNING   pid 1194, uptime 1 day, 17:36:48
constellation-server             RUNNING   pid 2888, uptime 1 day, 15:06:41

Vous pouvez également installer Constellation sur un système Windows (voir le guide).

En effet, le reverse proxy (ici Ngnix) qui sera installé sur un système Linux peut exposer un service tel que Constellation quelque soit le serveur sur lequel il est déployé. Le reverse proxy n’est pas nécessairement sur la même machine sur le ou les services à exposer.

Il est donc possible d’installer un serveur Linux avec Nginx pour exposer en SSL un serveur Constellation sur un système Windows de la même manière que nous pouvons installer un serveur Windows avec IIS pour exposer en SSL un serveur Constellation sur un système Linux !

Dans ce guide nous avons installer le serveur Constellation et le reverse proxy Nginx sur le même serveur, sous Linux Ubuntu 16.

Si vous souhaitez activer le HTTPS et donc ajouter un certificat SSL, vous devez nécessairement avoir un nom DNS qui pointe vers l’adresse IP (public) de votre serveur de reverse proxy.

Plusieurs options s’offre à vous :

• Si vous avez un nom de domaine, modifiez votre zone DNS pour ajouter un “host” (enregistrement A ou AAAA) vers l’adresse IP (public) de votre Constellation.
• SI vous n’avez pas de nom de domaine :
  • Achetez-en un ! Comptez environ 15€/an pour les extensions standards (.fr, .net, .com), 2,99€ HT par an pour  un .ovh
  • Utilisez un service de “Dynamic DNS” comme dyndns.fr, dyn.com ou autre
  • Certains FAI comme Free proposent d’attacher un nom DNS type xxxx.hd.free.fr à votre IP de connexion
  • Certains NAS comme Synology permettent aussi de créer un DDNS type xxx.synology.me vers votre IP de connexion

Dans le cas présent, j’ai crée l’entrée DNS “demo.internal.myconstellation.io” qui pointe vers l’adresse IP public du serveur Constellation installé sur un Ubuntu (le DNS doit pointer votre le serveur où sera installé le reverse proxy dans la mesure où tout passera par lui. Etant donné que le reverse proxy sera sur le même serveur que le service Constellation on peut dire que le DNS pointe vers le serveur Constellation).

Bien évidement, si votre serveur est installé dernière un routeur avec du NAT (typiquement sur un réseau local derrière une box Internet) vous devez configurer la redirection de port sur votre routeur/box internet.

Encore une fois, on part du principe que le serveur de R.P et Constellation sont sur le même serveur, donc la même IP interne.

Dans un premier temps redirigez seulement le port 8088 en tcp sur l’IP interne de votre serveur Constellation. A noter que nous supprimerons cette redirection une fois le reverse proxy installé.

Donc pour résumer et avant de démarrer, vous devez avoir votre serveur Constellation démarré répondant sur l’URL : http://<mon_nom_dns>:8088

Dans mon cas : http://demo.internal.myconstellation.io:8088 :

Voilà vous êtes prêt, votre Constellation est démarrée et elle répond bien sur un nom DNS public depuis l’internet.

Exposer Constellation derrière Nginx

Avant de démarrer il est recommandé de mettre à jour le référentiel du gestionnaire de package par la commande suivante :

sudo apt-get update

Ensuite installez le serveur Web Nginx avec la commande :

sudo apt-get install nginx

Les fichiers de configuration sont situés dans le répertoire “/etc/nginx/sites-available/” et pour les activer on crée un lien symbolique vers ces fichiers dans le répertoire “/etc/nginx/sites-enabled”.

Pour commencer désactivez la configuration par défaut par la commande ci-dessous :

sudo rm /etc/nginx/sites-enabled/default

Comme vous l’aurez compris le contenu de cette configuration par défaut est toujours présente dans le répertoire “/etc/nginx/sites-available/” mais non activée car on a supprimé le lien symbolique vers ce fichier dans le répertoire “site-enabled”.

Maintenant nous allons créer une configuration pour notre reverse proxy avec la commande :

sudo nano /etc/nginx/sites-available/constellation

Dans ce fichier, copiez le contenu suivant :

server {
    listen 80; listen [::]:80;
    server_name demo.internal.myconstellation.io;

    location / {
        proxy_pass http://localhost:8088;

        set $content_length_safe $http_content_length;
        if ($content_length_safe = "") {
            set $content_length_safe 0;
        }
        proxy_set_header Content-Length $content_length_safe;

        proxy_set_header Host $host;
        proxy_set_header Connection "";
        proxy_http_version 1.1;

        proxy_buffering off;
        proxy_cache off;
        proxy_connect_timeout 30;
        proxy_send_timeout 30;
        proxy_read_timeout 150;
    }
}

Vous devez modifier le paramètre “server_name” avec le nom DNS de votre serveur Constellation, dans le cas présent “demo.internal.myconstellation.io”.

Il est important de bien reprendre les mêmes options, notamment le “proxy_buffering” pour permettre les “server-Sent events” vers le serveur Constellation.

Dans le cas présent Nginx va « proxifer » les requêtes vers http://localhost:8088, c’est à dire au service Constellation (port 8088) installé sur le même serveur (localhost).

Tapez ensuite sur la combinaison de touches “Ctrl+X” pour quitter en prenant suivant d’enregistrer le fichier. Puis, pour activer cette configuration, créez le lien symbolique suivant :

sudo ln -s /etc/nginx/sites-available/constellation  /etc/nginx/sites-enabled/constellation

Avant de redémarrer Nginx, éditez le fichier de configuration global pour augmenter la taille maximale des requêtes entrantes afin de pouvoir uploader des packages Constellation sur le serveur (par défaut cette taille est fixée à 1Mo, autrement dit vous obtiendrez une erreur 413 « Request Entity Too Large » si vous tentez d’uploader un package de plus de 1Mo).

sudo nano /etc/nginx/nginx.conf

Sous la section « http », ajoutez l’option « client_max_body_size » (ou si l’option existe déjà, modifiez sa valeur) que nous fixerons à 100 Méga :

client_max_body_size 100M;

Pour finir, rechargez Nginx afin prendre en compte notre nouvelle configuration :

sudo systemctl reload nginx

Votre Constellation est maintenant accessible derrière Nginx sur le port 80.

Rendez-vous donc sur l’adresse http://<votre_nom_dns> (sans spécifier le port, car 80 par défaut) pour vérifier que le reverse proxy est opérationnel. Dans le cas présent http://demo.internal.myconstellation.io

Ce n’est donc plus Constellation qui répond mais notre serveur Nginx qui lui même communique avec le serveur Constellation local.

Donc pour résumer, sur le port 80 c’est le serveur Nginx qui répond en transférant au serveur Constellation sur le port 8088.

Note : si vous êtes dernière un routeur avec du NAT, n’oubliez pas d’ajouter la redirection du port 80 vers votre serveur Constellation interne. Par la même occasion vous pouvez supprimer la redirection du port 8088, ainsi tout passera nécessairement par Nginx.

Activer le HTTPS avec des certificats SSL Let’s Encrypt

Maintenant que votre service Constellation est exposé dernière le serveur Nginx vous allez pouvoir configurer différentes choses sur Nginx comme par exemple des restrictions d’accès , l’authentification, des limites (throttling) et bien d’autre chose. Dans le cas présent on va s’intéresser au support du SSL.

Pour activer le HTTPS, il vous faut un certificat SSL. Pour simplifier la démarche, Let’s Encrypt est une autorité de certification lancée en 2015 qui permet d’automatiser la génération de certificat. De plus le service est gratuit ! Les certificats sont valides trois mois, il faudra donc régulièrement les renouveler mais vous allez voir que cette action est entièrement automatisable.

Ici nous allons utiliser Certbot, un agent installé sur le serveur qui permet de générer et renouveler automatiquement les certificats SSL Let’s Encrypt.

Commencez par ajouter le repository suivant :

sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update

Ensuite installez Certbot pour Nginx :

sudo apt-get install python-certbot-nginx

Une fois installé, lancez la commande “certbot –nginx” en spécifiant le nom DNS vers votre serveur. Dans le cas présent :

sudo certbot --nginx -d demo.internal.myconstellation.io

L’assistant vous demandera tout d’abord votre adresse mail :

Après avoir accepté les conditions du service, l’assistant va automatiquement valider un challenge en interrogeant votre site Web (d’où la nécessité d’avoir exposé correctement votre serveur sur Internet avec le nom DNS spécifié), créer le certificat SSL et l’ajouter dans votre configuration Nginx.

Pour finir l’assistant vous proposera de modifier automatiquement la configuration de votre Nginx pour rediriger tous les appels HTTP (port 80) vers HTTPS (port 443).

Choisissiez l’option 2 pour activer cette redirection.

Et voilà, votre serveur Nginx est configuré avec le certificat SSL généré par Let’s Encrypt et toutes les requêtes seront redirigés en HTTPS et donc chiffrés !

Votre Constellation est maintenant protégée !

Rechargez la page dans votre navigateur (F5) sur l’URL http://<mon_nom_dns> vous constaterez la redirection automatique en https:// et le cadenas vert vous informant du chiffrement SSL :

(Note : pour les personnes derrières un NAT, n’oubliez pas non plus d’ajouter la redirection du port 443 vers votre serveur Nginx interne)

Pour vérifier le bon renouvellement du certificat vous pouvez utiliser la commande suivante :

sudo certbot renew --dry-run

Certbot a automatiquement installé un trigger dans systemd (ou crontab selon le système) pour réaliser le renouvellement et déploiement automatique de vos certificats avant leurs expirations.

Pour les plus curieux, vous pouvez jeter un œil dans le fichier “/etc/nginx/sites-available/constellation” pour voir les modifications apportées par Certbot.

Pour aller plus loin

Sécuriser le serveur avec un firewall UFW et fail2ban

Installer fail2ban

Fail2ban est un script tournant en tâche de fond qui va vérifier si les tentatives d’authentification SSH et Nginx; et en cas d’attaque, bannir l’IP grâce à iptables.

sudo apt-get install fail2ban

Pour plus d’info:  https://www.digitalocean.com/community/tutorials/how-to-protect-an-nginx-server-with-fail2ban-on-ubuntu-14-04

Installer UFW

UFW est un firewall applicatif. Pour l’installer :

sudo apt-get install ufw

Autorisez ensuite les services HTTP (nécessaire pour le challenge Let’s Encrypt), HTTPS (notre reverse proxy Nginx vers Constellation) et SSH :

sudo ufw allow http
sudo ufw allow https
sudo ufw allow ssh

Pour l’activer :

sudo ufw enable

Votre serveur Linux ne répondra plus que sur les ports 22 (ssh), 80 (http), 443 (https) en IPv4 et IPv6.

sebastien@ubuntu:~$ sudo ufw status
Status: active

To                         Action      From
--                         ------      ----
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
22                         ALLOW       Anywhere
80 (v6)                    ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)
22 (v6)                    ALLOW       Anywhere (v6)

Vous noterez que le port 8088 n’est maintenant plus accessible car bloqué par le firewall UFW. Il faudra forcement se connecter à Constellation via Nginx en HTTPS. N’oubliez pas alors de modifier l’URI de votre Constellation sur vos sentinelles existantes pour prendre en compte ce changement.

Ajouter d’autre application Web dernière votre reverse proxy SSL

Jusqu’au présent vous avez configuré un nom DNS type “demo.internal.myconstellation.io” qui pointe vers votre serveur Linux sur lequel le service Nginx répond en HTTP (80) et HTTPS (443) avec un certificat Let’s Encrypt pour “proxifier” les requêtes vers le service Constellation accessible localement sur le port 8088.

Vos utilisateurs se connectent donc forcement en HTTPS sur le reverse proxy pour accéder à Constellation !

La règle configurée dans Ngnix “proxifie” toutes les requêtes à partir de la racine « / » vers Constellation :

location / {
        proxy_pass http://localhost:8088;
....
}

Mais il est également possible d’adapter cette règle pour que votre reverse proxy ne soit plus exclusivement un passe-plat pour Constellation mais aussi pour vos autres services internes (une box domotique, un serveur Web, un objet connecté, une camera IP, etc…).

Vous aurez ainsi la possibilité d’exposer différents services Web internes dernière votre reverse proxy profitant d’un même port TCP (le 443) et donc d’un même canal de communication sécurisé (par le cryptage SSL).

Parmi les différentes options pour ce type de configuration :

1. Reverse proxy en fonction du “server_name”
2. Reverse proxy en fonction de la “location”

Reverse Proxy en fonction du server_name

Le principe est de rejouer ce tutoriel depuis le début pour chacune de vos applications à exposer.

Vous devrez ainsi créer une adresse DNS vers votre IP public pour chaque site, créer une configuration Nginx en changeant le « server_name » et « proxy_pass » vers la ressource interne à exposer et créer un certificat SSL avec Certbot pour tous vos sites créés.

Vous aurez ainsi une multitude de nom DNS qui pointerons tous vers votre serveur Nginx qui lui redirigera vers les ressources internes en fonction du « server_name ». Par exemple “constellation.mondomaine.fr”, “macamera.mondomaine.fr”, “jeedom.mondomaine.fr”, etc.. etc..

La configuration est simple car il s’agit de répéter ce tutoriel pour chaque service, par contre l’administration est un peu lourde et vous aurez autant de sous domaine et donc de certificat que de service à exposer.

Reverse Proxy en fonction de la “location”

Dans ce mode, nous gardons un seul site Nginx (celui configuré dans le fichier /etc/nginx/sites-available/constellation) et donc un seul nom de domaine (ici demo.internal.myconstellation.io) avec son certificat associé.

Cependant au lieu de “rediriger” les requêtes depuis la racine « / » vers Constellation nous allons créer plusieurs “location”.

Prenons un exemple pour bien comprendre. Ici le serveur Ngnix est installé sur la même que le serveur Constellation, donc localhost. Imaginons que dans ce même réseau LAN, j’ai par exemple un serveur ZoneMinder qui répond sur 192.168.0.10 et une box Jeedom sur 192.168.0.11.

Je pourrais éditer la configuration Nginx de cette façon :

location /constellation/ {
        proxy_pass http://localhost:8088/constellation/;

        proxy_set_header Host $host;
        proxy_set_header Connection "";
        proxy_http_version 1.1;

        proxy_buffering off;
        proxy_cache off;
        proxy_connect_timeout 30;
        proxy_send_timeout 30;
    }
    
    
location /zm/ {
        proxy_pass http://192.168.0.10/zm/;

        proxy_set_header Host $host;
        proxy_set_header Connection "";
        proxy_http_version 1.1;
    }
    
location /jeedom/ {
        proxy_pass http://192.168.0.11;

        proxy_set_header Host $host;
        proxy_set_header Connection "";
        proxy_http_version 1.1;
    }

Ainsi, en fonction du “path” demandé, un service différent me répondra :

• https://<mon_nom_DNS>/constellation : réponse du serveur Constellation
• https://<mon_nom_DNS>/zm  : réponse du serveur ZoneMinder
• https://<mon_nom_DNS>/jeedom : réponse du serveur Jeedom

Attention : si le serveur Constellation répond sur un “sous path”, comme ici “/constellation” il faut également modifier la configuration du serveur Constellation pour l’informer.

Pour cela modifiez le ficher “/opt/constellation-server/Constellation.Server.exe.config” :

sudo nano /opt/constellation-server/Constellation.Server.exe.config

Et modifier le listenUri pour reprendre la même structure d’URI, ici en ajoutant “/constellation” :

<listenUris>
    <uri listenUri="http://+:8088/constellation" />
</listenUris>

Pour finir, il faudra relancer le service Constellation pour prendre en compte ce changement :

sudo supervisorctl restart constellation-server

Voilà votre Constellation répond maintenant sur le /constellation, dans notre cas https://demo.internal.myconstellation.io/constellation :

Si maintenant on change le path pour “/zm” soit ici https://demo.internal.myconstellation.io/zm, c’est notre serveur ZoneMinder qui répondra :

On a donc un seul serveur en frontal, Ngnix qui écoute en HTTPS avec le certificat Let’s Encrypt pour sécuriser TOUS les échanges et qui, selon le “path” demandé, transféra les requêtes vers les différents services internes de votre réseau.

A noter que vous pouvez également utiliser des expressions régulières (regex) pour définir vos “locations”. Pour plus d’information : https://www.scalescale.com/tips/nginx/nginx-location-directive/

The post Exposer Constellation en HTTPS derrière un reverse proxy avec Nginx et Let’s Encrypt appeared first on Constellation.

Créer un scope

Un message Constellation est envoyé à un Scope qui représente le ou les destinataires du message.

Un scope Constellation est décrit dans l’API.NET par la classe “MessageScope”. Vous pouvez créer un scope avec la méthode statique “Create”.

Par exemple pour créer un scope vers les instances du package “MonPackage” de votre Constellation  :

MessageScope.Create("MonPackage")

Par défaut le type de scope est “Package”. La ligne ci-dessus est donc identique à la ligne :

MessageScope.Create(MessageScope.ScopeType.Package, "MonPackage")

Si vous souhaitez cibler une instance d’un package en particulier, vous devez spécifier la sentinelle sur laquelle est hébergée le package que vous ciblez :

MessageScope.Create("MaSentinelle/MonPackage")

Si vous souhaitez cibler plusieurs packages :

MessageScope.Create(MessageScope.ScopeType.Package, "MonPackage", "MonAutrePackage", "EncoreUnAutrePackage")

Bien entendu vous pouvez donner le nom d’une instance en particulier (sentinelle + package) ou juste le nom du package :

MessageScope.Create(MessageScope.ScopeType.Package, "MaSentinelle/MonPackage", "MonAutrePackage")

Le scope “Sentinel” permet de cibler tous les packages sur une sentinelle donnée. Vous pouvez définir autant de sentinelle que vous souhaitez :

MessageScope.Create(MessageScope.ScopeType.Sentinel, "MaSentinelle", "MonAutreSentinelle")

Le scope “Group” permet de cibler les packages qui sont abonnés à un groupe. Ici créons un scope pour tous les packages membre du groupe “GroupA” :

MessageScope.Create(MessageScope.ScopeType.Group, "GroupA")

Vous pouvez bien sûr définir autant de groupe dans un scope que vous souhaitez :

MessageScope.Create(MessageScope.ScopeType.Group, "GroupA", "GroupB", "GroupC")

Enfin vous pouvez créer des scopes pour cibler tous les clients connectés dans votre Constellation (All) ou tout le monde sauf l’émetteur (Others). Dans ces deux cas, il n’y a pas d’argument à spécifier :

MessageScope.Create(MessageScope.ScopeType.Others)

Envoyer un message avec le SendMessage

La méthode de base pour envoyer un message dans Constellation est “PackageHost.SendMessage”.

Vous devez définir trois arguments pour envoyer un message :

• Le scope (les destinataires de votre message)
• La clé du message (MessageKey)
• Le contenu du message (Data)

Comme vous le savez, on se sert des messages pour invoquer des méthodes d’autre packages. La clé du message est en fait le nom de la méthode (= le MessageCallback) à invoquer.

Prenons pour exemple les MessageCallbacks définis dans l’article précédent.

Pour invoquer le MessageCallback “MyMethod” sans paramètre (Data = null) on pourrait écrire :

PackageHost.SendMessage(MessageScope.Create("MonPackage"), "MyMethod", null);

Pour une méthode avec plusieurs paramètres, ils faut les encapsuler dans un tableau d’objet :

PackageHost.SendMessage(MessageScope.Create("MonPackage"), "MyMethodWithMultipleParameters", new object[] { "Un String", 123, true });

Cela fonctionne aussi avec des objets complexes. Par exemple pour invoquer notre MessageCallback “Logon” :

PackageHost.SendMessage(MessageScope.Create("MonPackage"), "Logon", new { User = "seb", Password = "seb" });

Avec l’API .NET on ne se sert généralement jamais de cette méthode “SendMessage” car vous avez à disposition le “SendMessageProxy” que nous allons découvrir ci-dessous.

Envoyer un message avec un proxy dynamique

La classe “SendMessageProxy” est un objet dynamique qui permet d’envoyer un message de la même manière que vous appelez une méthode en programmation .NET.

Pour créer un proxy dynamique vous devez au préalable avoir créer votre scope :

MessageScope scope = MessageScope.Create("MonPremierPackage");
dynamic proxy = new SendMessageProxy(scope);

Pour simplifier le code, vous pouvez utiliser la méthode d’extension “GetProxy()” sur le MessageScope :

MessageScope scope = MessageScope.Create("MonPremierPackage");
dynamic proxy = scope.GetProxy();

Attention, pour accéder aux méthodes d’extension du MessageScope vous devez ajouter le namespace “Constellation.Package” :

using Constellation.Package;

Une fois le proxy  dynamique créé il suffit d’appeler ‘”fictivement” une méthode pour envoyer le message.

Par exemple pour envoyer le message “MyMethod” avec un contenu du vide, on écrira simplement :

proxy.MyMethod();

Si votre message doit contenir plusieurs arguments :

proxy.MyMethodWithMultipleParameters("Un String", 123, true);

Ou encore avec notre MessageCallback “Logon” qui prend en argument un objet complexe :

proxy.Logon(new { User = "seb", Password = "seb" })

Ainsi vous pouvez invoquer un MessageCallback de n’importe quel package de la même façon que vous invoquerez une méthode de votre code .NET. La méthode invoquée est la clé du message et les arguments sont inclus dans le contenu du message.

Bien sûr avec la méthode d’extension vous pouvez faire tout cela en une ligne de code : créer le scope, récupérer le proxy dynamique et envoyer le message :

MessageScope.Create("MonPremierPackage").GetProxy().Logon(new { User = "seb", Password = "seb" });

Vous avez également à disposition la méthode “CreateMessageProxy” sur le PackageHost. Cette méthode permet de créer un scope et vous retourne le proxy dynamique.

Les deux lignes ci-dessous sont donc identiques :

dynamic proxy = MessageScope.Create("MonPremierPackage").GetProxy();
dynamic proxy = PackageHost.CreateMessageProxy("MonPremierPackage");

De ce fait, pour invoquer nos trois MessageCallbacks, on peut écrire simplement :

PackageHost.CreateMessageProxy("MonPremierPackage").MyMethod();
PackageHost.CreateMessageProxy("MonPremierPackage").MyMethodWithMultipleParameters("Un String", 123, true);
PackageHost.CreateMessageProxy("MonPremierPackage").Logon(new { User = "seb", Password = "seb" });

Tout comme la méthode “MessageScope.Create”, le “CreateMessageProxy” peut créer tout type de scope.

Par exemple, invoquons le MessageCallbacks “MyMessageCallback” avec deux arguments (un string et un datetime) sur tous les packages du groupe A et B de notre Constellation :

PackageHost.CreateMessageProxy(MessageScope.ScopeType.Group, "GroupA", "GroupB").MyMessageCallback("Mon Argument", DateTime.Now);

Invoquer un MessageCallback avec réponse – Utilisation des Sagas

Lorsque vous envoyez un message dans un scope vous pouvez ajouter un identifiant de Saga sur ce scope. Cela indiquera au destinataire que vous souhaitez une réponse en retour (plus d’info).

L’identifiant de Saga doit être aléatoire et unique. Vous avez une méthode d’extension “WithSaga” sur un MessageScope vous permettant de définir l’identifiant de la saga (SagaId) avec un GUID :

MessageScope.Create("MonPremierPackage").WithSaga();

La méthode d’extension vous retourne le MessageScope, vous pouvez donc directement récupérer le proxy dynamique et envoyer votre message :

MessageScope.Create("MonPremierPackage").WithSaga().GetProxy().Logon(new { User = "seb", Password = "seb" });

Pour la réception des réponses, vous avez une méthode “RegisterSagaResponseCallback” qui permet d’enregistrer la fonction à invoquer lors de la réponse :

PackageHost.RegisterSagaResponseCallback(sagaId, (reponse) =>
{
      // Response pour la saga "sagaId"
});

Pour simplifier le code, vous avez une méthode d’extension “OnSagaResponse” sur un MessageScope qui permet à la fois d’ajouter un identifiant de saga sur le scope (WithSaga) et d’enregistrer la fonction de retour.

De ce fait, vous pouvez en une seule ligne créer votre scope avec saga, définir le code qui sera invoqué à la réception la réponse, récupérer le proxy dynamique et invoquer votre MessageCallback avec ses paramètres :

MessageScope.Create("MonPremierPackage").OnSagaResponse((response) =>
{
    // Reponse de la saga
}).GetProxy().Logon(new { User = "seb", Password = "seb" });

Comme pour les MessageCallbacks, la méthode de réception d’une réponse d’une saga est invoquée dans un thread dédié dans lequel vous avez accès au contexte du message via la propriété “MessageContext.Current”.

Vous pouvez donc savoir quel est le package qui vous a répondu (Sender) ou encore quel était l’identifiant de la saga utilisée.

De plus, notez que la méthode OnSagaResponse est générique afin de pouvoir définir le type de retour (le cast sera réalisé automatiquement).

On peut donc écrire :

MessageScope.Create("MonPremierPackage").OnSagaResponse<bool>((response) =>
{
    PackageHost.WriteInfo("Reponse de {0} pour la saga {1}",                 
        MessageContext.Current.SagaId,
        MessageContext.Current.Sender.FriendlyName);

    PackageHost.WriteInfo(response ? "OK" : "DENIED");

}).GetProxy().Logon(new { User = "seb", Password = "seb" });

Notez également que si votre scope cible plusieurs packages (ex : si “MonPremierPackage” est déployé sur plusieurs sentinelles), votre fonction de traitement de la réponse sera invoquée plusieurs fois, pour chaque package qui répondra (car l’identifiant de Saga est le même).

Utiliser les “Tasks” (awaitable) pour attendre la réponse d’une saga

C’est une nouveauté de la 1.8 de Constellation. Pour bien comprendre, résumons ce que l’on connait déjà !

Lorsque vous invoquez une méthode sur le proxy dynamique, celui-ci envoie un message dans Constellation où la clé du message est le nom de la méthode invoquée et le contenu du message sont les paramètres de la méthode invoquée.

Ces deux lignes sont donc identiques :

PackageHost.SendMessage(MessageScope.Create("MonPackage"), "Logon", new { User = "seb", Password = "seb" });
MessageScope.Create("MonPremierPackage").GetProxy().Logon(new { User = "seb", Password = "seb" });

Sur la 2ème ligne, vous invoquez dynamiquement la méthode “Logon” sur le SendMessageProxy (créé par la méthode GetProxy()) pour envoyer (PackageHost.SendMessage) le message “Logon”.

Ces deux lignes font donc bien la même chose. Dans les deux cas le message est envoyé dans un scope qui ne porte pas de “SagaId” (donc aucune réponse n’est attendue).

Je rappelle également que vous pouvez créer un scope et récupérer son proxy dynamique directement avec la méthode PackageHost.CreateMessageProxy. On peut donc encore simplifier le code par la ligne :

PackageHost.CreateMessageProxy("MonPremierPackage").Logon(new { User = "seb", Password = "seb" });

D’un point de vue .NET, l’invocation dynamique de notre MessageCallback  “Logon » sur le proxy dynamique ne retourne rien, du moins il retourne “null”.

object result = PackageHost.CreateMessageProxy("MonPremierPackage").Logon(new { User = "seb", Password = "seb" });
// ici result = null

Observez maintenant le code ci-dessous :

Task<dynamic> reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });

Si vous examinez attentivement le MessageCallback que nous invoquons sur le proxy dynamique, on utilise une forme générique : au lieu d’avoir “Logon(xxxxx)”, on a ”Logon<bool>(xxxxx)”

Le fait de définir un type générique indique au proxy dynamique que vous attendez une réponse et donc qu’il s’agit d’une saga !

Le type générique est le type de réponse que vous attendez. Ici le MessageCallback “Logon” que vous avons écrit dans l’article précédent renvoi un booléen (bool). Vous pouvez utiliser n’importe quel type de base ou types complexes.

Si c’est la réponse est un objet anonyme ou si vous n’avez pas la définition de l’objet de retour dans votre code,  vous pouvez utiliser un “dynamic” (ex Logon<dynamic>(xxxx)).

Quoi qu’il en soit il est obligatoire d’invoquer le MessageCallback  en utilisant la syntaxe générique pour que le proxy dynamique ajoute automatiquement un identifiant de saga (WithSaga) lors de l’envoi du message.

Revenons donc à notre appel :

Task<dynamic> reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });

Le proxy dynamique nous retourne une ”Task<dynamic>”, c’est à dire une tache qui se charge d’envoyer et d’attendre la réception de la (première) réponse.

Vous pouvez bloquer le thread appelant jusqu’à ce que l’opération asynchrone soit terminée,  c’est à dire jusqu’à l’obtention de la réponse :

Task<dynamic> reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });
PackageHost.WriteInfo((bool)reponse.Result ? "OK" : "DENIED");

Ajouter des timeouts

Comme vous bloquez le thread appelant, prenez garde de mettre des gardes fou car nous n’avez aucune garantie qu’un package va répondre à votre saga. La tache pourrait ne jamais être complétée! Vous devriez donc attendre un certain temps avant de considérer la tache “hors délai”.

Par exemple attendons pendant 3 secondes maximum pour une réponse à notre Saga “Logon” :

Task<dynamic> reponse = PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });
if (reponse.Wait(3000) && reponse.IsCompleted)
{
    PackageHost.WriteInfo((bool)reponse.Result ? "OK" : "DENIED");
}
else
{
    PackageHost.WriteError("Aucune réponse !");
}

Async/Await

Aussi vous pouvez utiliser le pattern async/await, très pratique pour les packages UI WPF/Winform :

public async void Logon()
{
    bool reponse = await PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });
    PackageHost.WriteInfo(reponse ? "OK" : "DENIED");
}

Résultat de la tache

Notez bien que le proxy dynamique vous renverra toujours une “Task<dynamic>” quelque soit le type générique précisé au niveau de l’appel du MessageCallback (“bool” dans l’exemple du “Logon”).

Cependant le résultat de la tache (Task.Result) est bien du type que celui passé au niveau de l’appel du MessageCallback.

Si vous souhaitez toutefois récupérer une Task<T> où T est le type de retour de votre saga, vous devez créer une nouvelle tache pour réaliser le “cast” à la suite de la tache créée par Constellation.

Par exemple :

Task<dynamic> task = PackageHost.CreateMessageProxy("MonPremierPackage").Logon<bool>(new { User = "seb", Password = "seb" });
Task<bool> logonTask = task.ContinueWith<bool>(t => (bool)t.Result);

Annuler les taches

Lorsque l’on créé des taches en .NET on peut avoir besoin de leurs associer un jeton d’annulation : le CancellationToken.

Pour cela, il vous suffit de passer un “CancellationToken” comme dernier argument de votre invocation du MessageCallback :

CancellationTokenSource source = new CancellationTokenSource(1000);
CancellationToken token = source.Token;
try
{
    Task<dynamic> reponse = PackageHost.CreateMessageProxy("ConstellationPackageConsole1").Logon<bool>(new { User = "seb", Password = "seb" }, token);
    PackageHost.WriteInfo("Result = {0}", reponse.Result);
}
catch (AggregateException ae)
{
    foreach (Exception e in ae.InnerExceptions)
    {
        if (e is TaskCanceledException)
            PackageHost.WriteError("Unable to compute mean: {0}", ((TaskCanceledException)e).Message);
        else
            PackageHost.WriteError("Exception: " + e.GetType().Name);
    }
}
finally
{
    source.Dispose();
}

Dans l’exemple ci-dessus on crée un CancellationToken à partir d’un CancellationTokenSource que l’on passe en tant que dernier paramètre du MessageCallback.

Le CancellationTokenSource est ici construit pour annuler la tache après 1 seconde (1000 ms). Vous pouvez aussi annuler la tache en en appelant la méthode “Cancel” sur l’objet CancellationTokenSource :

source.Cancel();

Bien entendu, le proxy dynamique se sert de votre CancellationToken pour savoir quand annuler la tache. De plus notez bien que le proxy retire ce CancellationToken des paramètres du message (= le CancellationToken n’est pas envoyé dans le message !).

Prenez garde à bien gérer les exceptions, si la tache est annulée une exception “TaskCanceledException” est levée.

Le contexte du message

Dans une méthode marquée comme “MessageCallback” ou dans le callback de retour d’une saga (OnSagaResponse) vous pouvez toujours accéder au contexte de réception du message avec la propriété “MessageContext.Current”.

En effet les MessageCallbacks ou les callbacks de retour des sagas sont invoqués dans un thread à part ce qui permet de l’attacher au contexte de réception du message.

Cependant avec les taches, le résultat est dispatché dans le thread de l’appelant. Autrement dit, vous ne pouvez pas accéder au contexte courant (MessageContext.Current) !

La solution consiste à “demander” au proxy dynamique de vous “remplir” un contexte que vous avez initialisé au préalable.

Pour ce faire, commencez par déclarer un contexte vide (MessageContext.None) et passer l’instance comme dernier paramètre d’un appel :

MessageContext context = MessageContext.None;
Task<dynamic> reponse = PackageHost.CreateMessageProxy("ConstellationPackageConsole1").Logon<bool>(new { User = "seb", Password = "seb" }, context);
PackageHost.WriteInfo("Result = {0} - Response received from : {1}", reponse.Result, context.Sender.FriendlyName);

Une fois la tache complétée, la variable “context” sera remplie avec le contexte de la réponse lors de la réception. Vous pourrez donc accéder au contexte même dans vos taches.

Le MessageContext est toujours le dernière paramètr et le CancellationToken est donc l’avant dernier paramètre dans le cas où vous utilisez les deux :

CancellationTokenSource source = new CancellationTokenSource(1000);
CancellationToken token = source.Token;
MessageContext context = MessageContext.None;
try
{
    Task<dynamic> reponse = PackageHost.CreateMessageProxy("ConstellationPackageConsole1").Logon<bool>(new { User = "seb", Password = "seb" }, token, context);
    PackageHost.WriteInfo("Result = {0} - Response received from : {1}", reponse.Result, context.Sender.FriendlyName);
}
catch (AggregateException ae)
{
    foreach (Exception e in ae.InnerExceptions)
    {
        if (e is TaskCanceledException)
            PackageHost.WriteError("Unable to compute mean: {0}", ((TaskCanceledException)e).Message);
        else
            PackageHost.WriteError("Exception: " + e.GetType().Name);
    }
}
finally
{
    source.Dispose();
}

Générateur de code

Comme l’ensemble des MessageCallbacks sont déclarés dans la Constellation (sauf si ils sont marqués comme “Hidden”), il est possible de générer du code. Vous pouvez lire un article très complet sur le sujet ici.

Dans le menu contextuel de votre projet Visual Studio, sélectionnez “Generate Code” :

Sélectionnez votre Constellation et cliquez sur “Discover” :

Sélectionnez le ou les packages que vous souhaitez invoquer depuis votre package et cliquez sur “Generate”.

Le générateur de code va créer différentes classes présentant votre Constellation avec les packages sélectionnés (MessageCallbacks et StateObjects).

Dans notre cas nous allons inclure la définition des MessagesCallbacks de notre package “MonPremierPackage”.

Commençons donc par ajouter le using vers le MessageCallbacks de MonPremierPackage :

using ConstellationPackageConsole1.MonPremierPackage.MessageCallbacks;

Dans la classe générée “MyConstellation” vous retrouverez la liste des sentinelles et packages de votre Constellation :

Vous pourrez alors créer un scope personnalisé pour le package sélectionné :

Ce scope personnalisé contiendra l’ensemble des MessageCallbacks :

Et sur chaque MessageCallback, vous retrouvez les bons types de retour, les commentaires et les types complexes proprement générés :

De ce fait, pour reprendre l’exemple du MessageCallback “Logon”, on pourra écrire le code :

var context = MessageContext.None;
var token = new CancellationTokenSource(5000).Token;
var user = new UserInfo() { User = "seb", Password = "seb" };

var task = MyConstellation.Packages.MonPremierPackage.CreateMonPremierPackageScope().Logon(user, token, out context);

PackageHost.WriteInfo("Logon user {0} - Result = {1} - Sender : {2}", user.User, task.Result, context.Sender.FriendlyName);

N’hésitez pas lire cet article très complet sur la génération de code C# dans Constellation.

The post Envoyer des messages & Invoquer des MessageCallbacks appeared first on Constellation.