4nk/sdk_common
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
sdk_common/doc/Specs-Code.md

24 KiB
Raw Blame History

Code

1. Autheurs, validations, dates, versions, changement and historique

Cf. Git SDK COMMON

2. Table des matières

3. Documents de référence

Voir _Doc_references.md.

4. Choix des formats de données

4.1.  Strings

Les chaînes de caractères (String et &str) sont utilisées pour stocker du texte. String est une collection dynamique, modifiable, possédant une allocation sur le tas, tandis que &str est une vue immuable d'une séquence de caractères.

Cas d'usage commun :

  • Manipulation de texte : Lecture et écriture de fichiers texte, interfaces User, etc.
  • Traitement de données formatées comme le JSON ou le XML.
  • Communication réseau où les protocoles basés sur le texte sont utilisés (HTTP, SMTP).

4.2.  Hexadécimales

Les valeurs hexadécimales sont souvent utilisées pour représenter des données binaires de manière lisible, notamment dans le contexte de l'adressage mémoire, du débogage, ou de la représentation de couleurs en informatique.

Cas d'usage commun :

  • Affichage et édition de données binaires dans les éditeurs hexadécimaux.
  • Définition de couleurs dans les standards web (CSS).
  • Représentation compacte d'adresses mémoire ou de grandes valeurs binaires.

4.3.  Tableaux de bytes

Les tableaux de bytes (Vec<u8v> ou [u8] en Rust) sont utilisés pour manipuler des données binaires. Ils servent à stocker et transmettre des données dans un format qui n'est pas nécessairement du texte.

Cas d'usage commun :

  • Lecture et écriture de fichiers binaires, comme les images ou les fichiers audio/vidéo.
  • Communication réseau, en envoyant et recevant des données binaires sur les sockets.
  • Cryptographie, où les clés, les hash, et les signatures sont souvent manipulés sous forme de bytes.

Les tableaux de bytes sont au cœur de nombreuses opérations en informatique, en particulier dans les domaines nécessitant un traitement direct des données à bas niveau. La taille de ces tableaux varie en fonction de leur usage. Voici quelques tailles communes de tableaux de bytes, leurs usages typiques et des précautions à prendre lors de leur manipulation.

4.3.1. 8 Bytes (64 bits)

Souvent utilisé pour des nombres entiers longs, des adresses mémoire en architecture 64 bits, ou des timestamps. Tailles spécifiques à des protocoles ou formats de fichier : De nombreux formats de fichiers (comme les images, l'audio, la vidéo) et protocoles de communication ont des tailles de blocs ou de trames spécifiques qui ne suivent pas nécessairement un schéma basé sur la sécurité.

Précaution :

  • La compréhension des spécifications techniques et des contraintes de chaque format ou protocole est essentielle pour manipuler efficacement ces tailles de données.
  • Dans le contexte des formats de fichier et des protocoles de communication, assurez-vous de respecter les standards pour garantir la compatibilité et l'interopérabilité.

4.3.2. 16 Bytes (128 bits)

Usage :

  • Clés de cryptographie AES-128.
  • UUIDs (Universally Unique Identifiers).

Précaution :

  • Lors de l'utilisation pour la cryptographie, assurez-vous que la génération des clés est suffisamment aléatoire.
  • Pour les UUIDs, utilisez des bibliothèques éprouvées pour garantir l'unicité.

4.3.3.  32 Bytes (256 bits)

Usage :

  • Clés de cryptographie AES-256, souvent recommandées pour une sécurité accrue.
  • Empreintes SHA-256, couramment utilisées dans la sécurisation des données et la vérification d'intégrité.

Précaution :

  • Comme pour les clés de 128 bits, l'aléatoire dans la génération des clés est crucial.
  • Pour le SHA-256, être conscient de son utilisation appropriée et des limites dans les contextes de sécurité.

4.3.4.  64 Bytes (512 bits)

Usage :

  • Empreintes SHA-512, utilisées pour une sécurité accrue dans certains contextes.
  • Certains schémas de cryptographie asymétrique peuvent utiliser des clés de cette taille pour la signature numérique.

Précaution :

  • Les coûts en performance pour le traitement de telles tailles doivent être pris en compte, en particulier sur des appareils à ressources limitées.

4.3.5.   Précautions générales pour la manipulation des tableaux de bytes

  • Sécurité : Lors de la manipulation de données sensibles (comme les clés de cryptographie), assurez-vous que le stockage et le transfert des bytes soient sécurisés pour éviter les fuites d'informations.

  • Initialisation : Faites attention à l'initialisation des tableaux de bytes, en particulier pour les clés cryptographiques ou les données sensibles, pour éviter les valeurs prévisibles ou par défaut.

  • Performance : Les opérations sur les grands tableaux de bytes peuvent être coûteuses en termes de performance. Envisagez l'utilisation de buffers ou de streaming pour traiter de grandes quantités de données.

  • Interopérabilité : Lors du partage de données entre différents systèmes, assurez-vous que l'endianess et le format des données soient correctement gérés pour éviter les erreurs d'interprétation.

  • Libération de ressources : Pour les données sensibles, pensez à effacer (zeroize) les tableaux de bytes de la mémoire une fois qu'ils ne sont plus nécessaires, pour réduire le risque d'exposition.

4.4.  Format Base64

Le format Base64 est une méthode d'encodage qui permet de représenter des données binaires sous forme de chaînes de caractères ASCII. Il est couramment utilisé pour encoder des données binaires dans des contextes où les données textuelles sont préférées, comme dans le XML, le JSON, ou les courriels.

Cas d'usage commun :

  • Encodage d'images, de fichiers audio/vidéo pour leur intégration dans des fichiers HTML ou CSS.
  • Transmission de données binaires dans des protocoles de communication qui ne supportent que le texte.
  • Stockage sécurisé d'informations sensibles sous une forme encodée.

4.5.  Différence entre Bytes et Bits

Un byte est une unité de stockage informatique qui contient 8 bits. Un bit est la plus petite unité de données en informatique et peut prendre la valeur de 0 ou 1.

Cas d'usage commun :

  • Les bits sont utilisés pour les opérations au niveau le plus basique de l'informatique, comme les calculs binaires ou le stockage de valeurs booléennes.
  • Les bytes sont utilisés pour presque toutes les formes de stockage et de manipulation de données, comme le texte, les images, et les instructions de programme.

4.6. Little Endian et Big Endian

Ce sont deux manières différentes de stocker ou d'interpréter des séquences de bytes qui composent des nombres plus grands dans l'ordinateur. En Big Endian, le byte le plus significatif est stocké en premier. En Little Endian, c'est le byte le moins significatif qui est stocké en premier.

Cas d'usage commun :

  • Little Endian est utilisé par la majorité des architectures de processeurs modernes, y compris x86 et x86_64.
  • Big Endian est souvent utilisé dans les réseaux, comme dans le protocole IP pour l'ordre des octets des adresses.
  • La conversion entre les deux est nécessaire lors de l'interopérabilité réseau entre différentes architectures ou lors du traitement de fichiers binaires d'origines diverses.

Cette vue d'ensemble donne une idée de l'importance et de la polyvalence de ces concepts en programmation Rust et plus largement en informatique. Chaque élément a des cas d'usage spécifiques où il brille particulièrement bien, aidant les développeurs à choisir la meilleure approche pour leurs besoins.

4.7.  Conversions de données

Aborder les conversions entre différents formats de données est essentiel dans le développement de logiciels, notamment en Rust, où la gestion de la mémoire et des types est centrale.

4.7.1. Conversion entre Strings et Hexadécimales

  • Préconisation : Utilisez des bibliothèques éprouvées pour convertir les chaînes de caractères en hexadécimales et vice versa. Ces opérations peuvent sembler simples, mais gérer correctement tous les cas d'erreur potentiels peut être délicat.

  • Retour d'expérience : La conversion directe peut être tentante, mais attention aux données non représentables en hexadécimal directement (comme les caractères spéciaux ou non ASCII). La validation des entrées est cruciale pour éviter les erreurs.

4.7.2. Conversion entre Tableaux de Bytes et Format Base64

  • Préconisation : Lors de la conversion de données binaires (comme des tableaux de bytes) en Base64, assurez-vous de comprendre l'impact sur la taille des données. La représentation en Base64 augmente la taille des données d'environ 33%. Cela peut être important pour les performances réseau et le stockage.

  • Retour d'expérience : L'utilisation de Base64 est très pratique pour intégrer des ressources binaires dans des formats textuels (comme des images en HTML/CSS). Cependant, cette facilité d'utilisation doit être équilibrée avec la considération de l'augmentation de la taille des données.

4.7.3. Conversion entre Bytes et Bits

  • Préconisation : Soyez conscient de l'endianess lorsque vous travaillez avec des conversions de bits à bytes et vice versa. Des erreurs dans ces conversions peuvent entraîner des bugs subtils et difficiles à détecter, surtout lors de l'interopérabilité entre différents systèmes ou protocoles.

  • Retour d'expérience : Dans les applications bas niveau ou embarquées, ces conversions sont courantes. L'utilisation explicite de types de données et de fonctions de conversion aide à maintenir la clarté du code et à éviter les erreurs.

4.7.4. Gestion de Little Endian et Big Endian

  • Préconisation : Lorsque vous travaillez dans un environnement hétérogène (différentes architectures de machines ou réseaux), il est essentiel d'être explicite sur l'endianess des données lors de leur envoi, réception, ou stockage. Utilisez des fonctions de conversion dédiées pour modifier l'ordre des bytes lorsque nécessaire.

  • Retour d'expérience : Les erreurs d'endianess sont parmi les plus déroutantes à diagnostiquer. Documenter clairement l'endianess attendue pour chaque interface peut sauver des heures de débogage.

4.7.5. Bonnes Pratiques Générales

  • Validation des données : Toujours valider les données en entrée lors des conversions pour éviter des erreurs inattendues ou des vulnérabilités de sécurité.
  • Performance : Soyez conscient de l'impact sur les performances des conversions, surtout dans des boucles critiques ou pour des données volumineuses.
  • Clarté du code : Préférez des fonctions ou des bibliothèques de conversion explicites plutôt que des manipulations manuelles, pour la clarté du code et sa maintenabilité.

Les conversions entre différents formats de données sont omniprésentes en programmation. Une compréhension approfondie de ces opérations et une attention particulière aux détails peuvent grandement améliorer la robustesse et l'efficacité de vos applications.

5. Recommandations entre l'usage de HashMap ou d'un Vec (en Rust)

En Rust, le choix entre l'utilisation d'un HashMap et d'un Vec dépend largement de la nature de vos données et de ce que vous cherchez à accomplir. Voici quelques points à considérer pour faire le bon choix :

5.1. Utilisez un Vec si

  • Les données sont accessées par index: Vec est idéal lorsque vous travaillez avec une collection ordonnée d'éléments accessibles par leur index. L'accès, l'insertion et la suppression à la fin du vecteur sont très rapides.

  • Performance pour les petits ensembles de données: Pour des petites collections, Vec peut être plus performant que HashMap en raison de la simplicité de sa structure de données et de son moindre coût en mémoire.

  • Vous avez besoin d'ordre: Si l'ordre des éléments est important pour votre application, Vec maintient l'ordre d'insertion, tandis que HashMap ne le fait pas.

5.2. Utilisez un HashMap si

  • Recherche rapide par clé: HashMap excelle lorsque vous avez besoin de chercher, d'insérer ou de supprimer des éléments en utilisant une clé. La complexité temporelle de ces opérations est en moyenne O(1), ce qui est particulièrement efficace pour de grands ensembles de données.

  • Accès par clé au Lieu de l'index: Lorsque vos données sont mieux identifiées par des clés uniques (comme des noms d'User, des identifiants, etc.) plutôt que par des indices numériques.

  • Évitement des doublons pour les clés: HashMap assure qu'il n'y a pas deux entrées avec la même clé, ce qui peut être essentiel pour certaines applications.

5.3.  Recommandations Générales

  • Évaluez la taille de votre collection: Pour des collections très petites, la différence de performance entre Vec et HashMap peut être négligeable, et d'autres facteurs, comme l'ordre des éléments ou la clarté du code, peuvent prévaloir.

  • Considérez l'évolutivité: Si vous prévoyez que votre collection de données va croître de manière significative, il peut être judicieux de choisir la structure de données qui sera la plus efficace à long terme, même si elle est légèrement plus complexe ou moins performante pour des petites tailles.

  • Profiling et optimisation: N'hésitez pas à utiliser des outils de profiling pour mesurer les performances réelles de votre application avec les deux structures de données. Ce qui est théoriquement plus rapide ne l'est pas toujours en pratique, en raison de l'overhead, de la localité de la mémoire, et d'autres facteurs systèmes.

  • Considération de la mémoire: HashMap utilise plus de mémoire que Vec en raison de sa structure interne plus complexe. Si la mémoire est une contrainte, cela peut influencer votre choix.

En résumé, le choix entre Vec et HashMap en Rust doit être guidé par les spécificités de vos données et par les opérations que vous prévoyez d'effectuer. Prendre le temps de comprendre ces structures de données et leurs implications peut grandement affecter la performance et la clarté de votre code.

6. Gestion des erreurs

Les processus doivent continuer malgré des "sous" traitements/threads en échec et les fonctions doivent être catch si il y a une possiblité d'interuption.

Stratégie de gestion des erreurs et de reporting pour faciliter le débogage et améliorer la résilience du système.

Tous les flux sont reçus par autant de relais et de Members de même rôles. Un arbitrage est possible pour confronter les données dans le temps et par origines. Les résultats permettent d'améliorer les listes de Members par un système de réputation calculable par chacun de façon autonome en rapport à sa propre expérience.

Les arrêts de la blockchain dans son ensemble n'entraînent pas d'interruption de service, car les horodatages sont non bloquants, l'impact est une diminution de la preuve le temps de "ré-ancrer" ce qui n'aurait pas pu l'être. L'arrêt de nœuds de la blockchain pourrait ralentir la propagation des informations dans les scénarios les plus critiques, sans impact majeur sur le fonctionnement.

Les arrêts des Members dans les Process dans leur ensemble n'entraînent pas d'interruption de service, les confirmations restent en attente, toujours relayées jusqu'au rétablissement des services. L'arrêt de Members des rôles critiques des Process pourrait empêcher le démarrage des services et pour les gestionnaires des Members, l'accès au réseau pour les User n'ayant qu'un processus connu avec un rôle dedans. Cela n'entraîne pas une perte des données. Cette incapacité pourrait venir corrompre des signatures attendues dans un délai. Dans ce cas, le rôle "resolve" des Process est en charge de l'arbitrage pour la bonne restitution des actions.

Les parties prenantes ont tous les moyens organisationnels dans les Process, pour procéder au bon redémarrage des services en cas de dégradations et de situations inattendues, avec le versionning des relais et des Members des rôles; ainsi que des conditions contractuelles avec leurs implications opérationnelles et possiblement économiques.

7. Journalisation et monitoring

Tous les User reçoivent les mêmes flux qu'ils se relaient et se restituent au démarrage, tous les flux ont une empreinte horodatée sur une timechain et peuvent être demandés unitairement entre parties, avec le même niveau de confidentialité par rôles. Les Pcd sont les listes à jour de l'état de validation de tous les éléments échangés, et les Prd sont toutes les signatures échangées sur les flux; en mémoire côté User, par "session" sur un nœud, pour un Process (possible de segmenter par zones et services).

Le monitoring comme la journalisation, ne sont pas possibles et pas pertinents sur les relais qui ne sont pas critiques unitairement, tous les flux sont fongibles, chiffrés, anonymes, et peuvent passer par des relais non révélés. Cependant, l'optimisation des listes de pairs et de contrats, pourrait passer par un système de réputation qui nécessitera un historique. À ce stade, la gestion "qualitative" et "quantitative" des relais et des contrats est gérée en mémoire, non persistée et restaurée par chaque connexion à un nouveau pair.

La timechain permet de monitorer l'activité générale sur la side chain avec un nombre de jetons échangés (le même nombre à chaque Envelope ) et des ancrages critiques sont monitorables sur le mainnet publiquement par n'importe qui (mais non exploitable fonctionnellement). Ainsi seul le bon fonctionnement est monitorable, par tous, facilement, sans métadonnées exploitables pour ce qui est des usages qui restent donc confidentiels.

8. Tests

8.1. Stratégie de test

À l'issue du développement en ScrumBan, chaque ticket fait l'objet d'une revue de code, et d'un test par un testeur.

8.2. Plan pour les tests unitaires

Les tests unitaires seront ajoutés par un testeur, ainsi toutes les fonctionnalités reçues auront un test unitaire.

8.3. Plan d'intégration

L'intégration se réalise par sprint hebdomadaire.

L'ensemble des fonctionnalités livrées dans le sprint doivent être testées dans un parcours d'intégration écrit et testé par un testeur en fin de sprint.

8.4. Plan de charge

Tous les 2 sprints, des tests aux limites sont définis et mis en œuvre par un testeur depuis la simulation des comportements des User.

9. Outils et les librairies à utiliser

Respect des normes de syntaxe Rust.

Utilisation de Visual Studio (pour le partage de configurations).

À l'étude : revues et pilotage par la documentation depuis une IA et partage d'un chat IA pour la base de connaissance.

  • Environnement : navigateur (tous dispositifs), et relais sous Debian.

  • Développement : pour compilation Wasm.

  • Pas de base de données sauf IndexedDB présent nativement pour les navigateurs et les applications mobiles.

  • Librairies : rust-bitcoin, rand, hex, bech32, shamir_secret_sharing, uuid, sha2, chrono, aes-gcm, base64, wasm-bindgen, serde, serde_json dans leurs dernières versions.

  • Librairies de tests : Cargo test

10. Critères d'acceptation

Critères de validation pour que le système puisse être considéré comme prêt pour la production :

  • Tous les parcours User fonctionnels.
  • Tous les tests unitaires présents et parcourus.
  • Tous les tests d'intégration présents et parcourus.
  • Aucun bug bloquant.
  • 10 bugs majeurs.
  • 20 bugs mineurs.
  • Contrôles manquants clairement précisés.
  • Documentation manquante clairement précisée.
  • Autres tests manquants clairement précisés.

11. CI/CD

GitLab CI : TBD

12. Maintenance

La liste des dépendances doit être maintenue dans le readme des projets, mise à jour à chaque fin de sprint. Les tests de fin de sprint doivent intégrer une revue des dernières versions et alertes sur les librairies en dépendance.

13. Exemples de Code

14. Todo