SDK IronFlock

Le SDK IronFlock permet à vos applications edge d’interagir avec la plateforme IronFlock. Il existe en trois langages — Python, JavaScript et Go — avec les mêmes fonctionnalités, documentés côte à côte ci-dessous. Il gère l’authentification automatiquement lorsqu’il s’exécute sur un appareil enregistré et fournit des fonctions pour publier des données, interroger l’historique, appeler des procédures distantes entre appareils et mettre à jour les métadonnées des appareils.

Cette page est le guide des trois SDK. Le README de chaque SDK sur GitHub en constitue la référence complète : IronFlock/sdk-py, IronFlock/sdk-js et IronFlock/sdk-go.

Installation

pip install ironflock

npm install ironflock

go get github.com/ironflock/sdk-go

Démarrage rapide

import asyncio
from datetime import datetime, timezone
from ironflock import IronFlock
 
async def main():
    while True:
        await ironflock.publish_to_table("sensordata", {
            "tsp": datetime.now(timezone.utc).isoformat(),
            "temperature": 22.5,
            "humidity": 60
        })
        await asyncio.sleep(5)
 
ironflock = IronFlock(mainFunc=main)
ironflock.run()

import { IronFlock } from "ironflock";
 
const ironflock = new IronFlock();
await ironflock.start();
 
setInterval(async () => {
    try {
        await ironflock.publishToTable("sensordata", [{
            tsp: new Date().toISOString(),
            temperature: 22.5,
            humidity: 60
        }]);
    } catch (e) {
        console.error("Publish failed:", e);
    }
}, 5000);

package main
 
import (
	"context"
	"log"
	"time"
 
	ironflock "github.com/ironflock/sdk-go"
)
 
func main() {
	ifl, err := ironflock.New()
	if err != nil {
		log.Fatal(err)
	}
 
	// Run connects, runs main, and shuts down when main returns or on SIGINT/SIGTERM.
	err = ifl.Run(context.Background(), func(ctx context.Context) error {
		ticker := time.NewTicker(5 * time.Second)
		defer ticker.Stop()
		for {
			row := ironflock.Row{"tsp": time.Now(), "temperature": 22.5, "humidity": 60}
			if err := ifl.PublishToTable(ctx, "sensordata", row); err != nil {
				log.Print(err)
			}
			select {
			case <-ctx.Done():
				return nil
			case <-ticker.C:
			}
		}
	})
	if err != nil {
		log.Fatal(err)
	}
}

Lorsqu’il est utilisé à l’intérieur d’un conteneur d’application IronFlock, le SDK lit automatiquement les identifiants de connexion depuis l’environnement — aucune configuration manuelle n’est nécessaire. Chaque ligne que vous écrivez dans une table porte un tsp, son horodatage (voir publishToTable).

Options du constructeur

ironflock = IronFlock(
    mainFunc=main,           # async function to run after connecting
    serial_number="abc123",  # override device serial (optional)
    reconnect_window=60,     # seconds an operation rides out a platform restart (optional)
)

const ironflock = new IronFlock({
    serialNumber: "abc123",    // device serial (env: DEVICE_SERIAL_NUMBER)
    deviceKey: "12",           // numeric device key (env: DEVICE_KEY)
    appName: "MyApp",          // app name (env: APP_NAME)
    swarmKey: 10,              // project key (env: SWARM_KEY)
    appKey: 20,                // app key (env: APP_KEY)
    env: "PROD",               // "DEV" or "PROD" (env: ENV)
    reconnectWindowMs: 60000,  // how long an operation rides out a platform restart
});

ifl, err := ironflock.New(
	ironflock.WithSerialNumber("abc123"),          // device serial (env: DEVICE_SERIAL_NUMBER)
	ironflock.WithReconnectWindow(60*time.Second), // how long an operation rides out a platform restart
)
if err != nil {
	log.Fatal(err) // no serial number in the environment or the options
}

Publier des données

publishToTable / publish_to_table

Écrit un enregistrement de données dans une table de flotte. Le nom de la table doit correspondre à une table définie dans le data-template.yml de votre application. Le SDK achemine automatiquement les données vers la bonne base de données du projet.

Cette méthode est identique à appendToTable / append_to_table : elle appelle la procédure d’ajout de la table et survit donc à un redémarrage de la plateforme — elle attend la connexion au plus pendant la fenêtre de reconnexion et réessaie tant que le backend de données ne sert pas encore la table — et elle lève une exception (rejette, renvoie une erreur) lorsque le backend de données refuse la ligne. Aucune ligne n’est perdue pendant le redémarrage de la plateforme.

Jusqu’à la version 1.9.1 incluse, les trois SDK publiaient plutôt la ligne sur le topic d’écriture de la table : une ligne publiée pendant le redémarrage du backend de données était perdue, et une ligne refusée était abandonnée sans erreur. Désormais, une telle ligne fait échouer l’appel — par exemple une ligne sans tsp, ou une ligne destinée à une table absente du data template (une fois la fenêtre de reconnexion écoulée).

from datetime import datetime, timezone
 
await ironflock.publish_to_table("sensordata", {
    "tsp": datetime.now(timezone.utc).isoformat(),
    "temperature": 22.5,
    "humidity": 60,
    "device_id": "sensor-001"
})

await ironflock.publishToTable("sensordata", [{
    tsp: new Date().toISOString(),
    temperature: 22.5,
    humidity: 60,
    device_id: "sensor-001"
}]);

err := ifl.PublishToTable(ctx, "sensordata", ironflock.Row{
	"tsp":         time.Now(),
	"temperature": 22.5,
	"humidity":    60,
	"device_id":   "sensor-001",
})
if err != nil {
	return err
}

Le backend de données lit la ligne depuis le premier argument : un dict en Python, le premier élément du tableau en JavaScript, le premier argument positionnel en Go (une map ou une struct). Les arguments nommés supplémentaires — en Go, une valeur ironflock.Kwargs parmi les arguments — ne sont lus que pour les colonnes que le data template leur associe (kwargs.<name>).

Chaque ligne a besoin d’un tsp. Chaque table possède une colonne tsp obligatoire, l’horodatage de la ligne — par ex. une chaîne ISO 8601, ou en Go un time.Time, envoyé en RFC 3339 en UTC —, que le backend de données lit dans la ligne, sauf si le data template l’associe à une autre source. Il refuse une ligne sans tsp, comme décrit sous appendToTable / append_to_table.

Lignes partielles dans les tables d’entités. Dans une table dotée d’une clé d’entité (maintainLatestFlagFor), une ligne peut ne contenir que la clé d’entité, tsp et les colonnes qui changent. Une colonne que la ligne omet conserve la valeur précédente de l’entité ; une colonne envoyée comme None / null / nil est effacée. Qu’un champ compte comme omis dépend de la façon dont vous construisez la ligne :

• Python : une clé dont la valeur est None est envoyée comme null et efface la colonne. Retirez la clé du dict pour conserver l’ancienne valeur.
• JavaScript : une propriété dont la valeur est undefined disparaît du payload, elle conserve donc l’ancienne valeur. Mettez-la à null pour effacer la colonne.
• Go : un champ de struct marqué omitempty ou omitzero est omis lorsqu’il est vide, il conserve donc l’ancienne valeur. Sinon, un champ pointeur nil, comme une valeur nil dans un ironflock.Row, est envoyé comme null et efface la colonne.

Il en va de même pour les quatre méthodes d’écriture. Dans une table sans clé d’entité, une colonne que la ligne omet est stockée comme NULL.

appendToTable / append_to_table

Ajoute des données à une table de flotte via un appel de procédure distante : une ligne refusée est une erreur. publishToTable / publish_to_table fait de même ; la seule différence est le nom que le message d’erreur donne à l’opération.

result = await ironflock.append_to_table("sensordata", {
    "tsp": datetime.now(timezone.utc).isoformat(),
    "temperature": 22.5,
    "humidity": 60
})

const result = await ironflock.appendToTable("sensordata", [{
    tsp: new Date().toISOString(),
    temperature: 22.5,
    humidity: 60
}]);

result, err := ifl.AppendToTable(ctx, "sensordata", ironflock.Row{
	"tsp":         time.Now(),
	"temperature": 22.5,
	"humidity":    60,
})
if err != nil {
	return err // the row was refused, or the call failed
}
log.Println(result.Value())

La ligne a besoin d’un tsp, comme pour publishToTable. Le backend de données refuse une ligne sans tsp avec wamp.error.runtime_error et sans raison ; l’erreur du SDK ajoute alors “the data backend refused the row without a reason — a missing tsp is the usual cause; see the error-logs table”. Les refus typés, comme un disque plein sur une appliance, sont listés sous Refus du backend de données.

publishRowsToTable / publish_rows_to_table

Écrit plusieurs lignes dans un seul message (insertion en masse) dans une table de flotte. La plateforme insère l’intégralité du lot de manière atomique (tout ou rien) en une seule opération. Utilisez ceci pour les données à haute fréquence, où un aller-retour par ligne serait trop coûteux. Cette méthode est identique à appendRowsToTable / append_rows_to_table : elle appelle la procédure d’ajout en masse, survit comme publishToTable à un redémarrage de la plateforme et échoue lorsque le backend de données refuse le lot.

await ironflock.publish_rows_to_table("sensordata", [
    {"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
    {"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
])

await ironflock.publishRowsToTable("sensordata", [
    { tsp: "2024-01-15T10:30:00.000Z", temperature: 22.5 },
    { tsp: "2024-01-15T10:30:01.000Z", temperature: 22.7 },
]);

err := ifl.PublishRowsToTable(ctx, "sensordata", []ironflock.Row{
	{"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
	{"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
})
if err != nil {
	return err
}

Le second argument est une liste non vide d’objets de lignes à insérer, chacun avec son propre tsp — en Go, une slice de lignes ([]ironflock.Row, []map[string]any ou une slice de structs). Un lot que le backend de données refuse — parce qu’une ligne n’a pas de tsp, par exemple — fait échouer l’appel, et aucune de ses lignes n’est stockée. (Jusqu’à la version 1.9.1 incluse, les SDK publiaient le lot sur le topic bulk de la table, où un lot refusé était abandonné sans erreur.)

appendRowsToTable / append_rows_to_table

Ajoute plusieurs lignes via un seul appel de procédure distante (insertion en masse) dans une table de flotte. La plateforme insère l’intégralité du lot de manière atomique (tout ou rien) : si une ligne est invalide, le lot entier est rejeté et rien n’est persisté. publishRowsToTable / publish_rows_to_table fait de même. Chaque ligne a besoin de son propre tsp ; les refus sont ceux d’appendToTable, y compris l’indication pour un lot refusé sans raison.

result = await ironflock.append_rows_to_table("sensordata", [
    {"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
    {"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
])
# result -> {"success": True, "count": 2}

const result = await ironflock.appendRowsToTable("sensordata", [
    { tsp: "2024-01-15T10:30:00.000Z", temperature: 22.5 },
    { tsp: "2024-01-15T10:30:01.000Z", temperature: 22.7 },
]);
// result -> { success: true, count: 2 }

result, err := ifl.AppendRowsToTable(ctx, "sensordata", []ironflock.Row{
	{"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
	{"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
})
if err != nil {
	return err // the whole batch was refused, or the call failed
}
log.Println(result.Value()) // map[count:2 success:true]

reportError / report_error

Signale une erreur applicative dans la table error-logs de votre flotte. Il s’agit d’un wrapper pratique au-dessus de publishToTable / appendToTable : il estampille la ligne avec source: "app", un niveau de gravité level et un horodatage, puis l’écrit comme n’importe quelle ligne de table normale. L’erreur arrive dans la même table error-logs que celle utilisée par les erreurs système de fleetdb (étiquetées source: "system"), elle est donc interrogeable avec getHistory, diffusable en flux avec subscribeToTable / subscribe_to_table, utilisable dans les modèles de tableaux et livrée en temps réel sur transformed.error-logs — sans déclencher la notification d’erreur système de la plateforme.

# Writes a row to the error-logs table
await ironflock.report_error("Sensor read timed out", level="warning")
 
# Pass an exception to capture its traceback (falls back to the message)
try:
    risky_operation()
except Exception as err:
    await ironflock.report_error(err)
 
# Show the operator a friendlier line than the raw error
await ironflock.report_error(
    "Calibration failed: offset 0.42 out of range",
    user_message="Please recalibrate the sensor",
)

// Writes a row to the error-logs table
await ironflock.reportError("Sensor read timed out", { level: "warning" });
 
// Pass an Error to capture its stack (falls back to the message)
try {
    riskyOperation();
} catch (err) {
    await ironflock.reportError(err);
}
 
// Show the operator a friendlier line than the raw error
await ironflock.reportError("Calibration failed: offset 0.42 out of range", {
    userMessage: "Please recalibrate the sensor",
});

// Writes a row to the error-logs table
ifl.ReportError(ctx, "Sensor read timed out", ironflock.ReportErrorOptions{Level: ironflock.LevelWarning})
 
// Pass an error: it is recorded with %+v, so an error that carries a stack trace includes it
if err := riskyOperation(); err != nil {
	ifl.ReportError(ctx, err)
}
 
// Show the operator a friendlier line than the raw error
_, err := ifl.ReportError(ctx, "Calibration failed: offset 0.42 out of range", ironflock.ReportErrorOptions{
	UserMessage: "Please recalibrate the sensor",
})
if err != nil {
	return err
}

La ligne est { tsp, msg, user_message, source: "app", level } : msg contient le texte technique (une trace ou une pile d’appels), user_message la ligne qu’affiche la notification d’erreur du board — le message utilisateur que vous passez ou, à défaut, le message lui-même.

Paramètres :

En Python, les options sont des arguments nommés (report_error(error, level=..., append=..., tsp=..., user_message=...)) ; en JavaScript, elles sont passées via un objet d’options (reportError(error, { level, append, tsp, userMessage })) ; en Go, via une struct (ReportError(ctx, errOrMsg, ironflock.ReportErrorOptions{Level, Append, Tsp, UserMessage})), où errOrMsg est une error ou une chaîne, Level l’une des valeurs ironflock.LevelError, LevelWarning, LevelInfo, LevelDebug, et où le *Result renvoyé est le résultat de l’insertion.

publish

Publie un message sur un topic WAMP qui vous est propre. Utilisez ceci pour la messagerie personnalisée ou les événements qui ne correspondent pas à une table de base de données. Le routeur réserve certains noms à la plateforme — voir URI autorisées pour une app.

Comme les écritures dans les tables, publish ajoute les métadonnées de l’appareil aux arguments nommés : DEVICE_SERIAL_NUMBER, DEVICE_KEY et DEVICE_NAME. Si vous passez vous-même un argument nommé portant l’un de ces noms, c’est le vôtre qui l’emporte.

Sans connexion, publish attend une connexion au plus pendant la fenêtre de reconnexion (60 secondes par défaut, voir Fiabilité de la connexion), si bien qu’une publication survit à une courte coupure. Le message est ensuite envoyé une seule fois, jamais retenté. Le routeur acquitte un message auquel personne n’est abonné : un abonné hors service entre-temps le manque donc.

await ironflock.publish("com.myapp.alerts", {
    "level": "warning",
    "message": "Temperature threshold exceeded"
})

await ironflock.publish("com.myapp.alerts", [{
    level: "warning",
    message: "Temperature threshold exceeded"
}]);

err := ifl.Publish(ctx, "com.myapp.alerts", map[string]any{
	"level":   "warning",
	"message": "Temperature threshold exceeded",
})
if err != nil {
	return err // the router refused the publish, or there was no connection
}

Interroger les données historiques

getHistory

Récupère des données historiques depuis une table de flotte ou un transform : les lignes correspondantes les plus récentes, par ordre croissant de tsp. Supporte le filtrage, les plages temporelles et la pagination.

# Simple query
data = await ironflock.getHistory("sensordata", {"limit": 100})
 
# Query with time range and filters
data = await ironflock.getHistory("sensordata", {
    "limit": 500,
    "offset": 0,
    "timeRange": ["2026-01-01T00:00:00Z", "2026-03-01T00:00:00Z"],
    "filterAnd": [
        {"column": "temperature", "operator": ">", "value": 20},
        {"column": "humidity", "operator": "<=", "value": 80}
    ]
})
 
# Current value(s) only: the "latest" marker returns the newest row per entity
current = await ironflock.getHistory("sensordata", {
    "limit": 100,
    "filterAnd": [{"latest": True}]
})
 
# One field of a large json column: the column comes back pruned to its paths
readings = await ironflock.getHistory("sensordata", {
    "limit": 100,
    "columns": ["json_data"],
    "columnPaths": ["json_data.sensor.temp"],
})

// Simple query
const data = await ironflock.getHistory("sensordata", { limit: 100 });
 
// Query with time range and filters
const data = await ironflock.getHistory("sensordata", {
    limit: 500,
    offset: 0,
    timeRange: ["2026-01-01T00:00:00Z", "2026-03-01T00:00:00Z"],
    filterAnd: [
        { column: "temperature", operator: ">", value: 20 },
        { column: "humidity", operator: "<=", value: 80 },
    ],
});
 
// Current value(s) only: the `latest` marker returns the newest row per entity
const current = await ironflock.getHistory("sensordata", {
    limit: 100,
    filterAnd: [{ latest: true }],
});
 
// One field of a large json column: the column comes back pruned to its paths
const readings = await ironflock.getHistory("sensordata", {
    limit: 100,
    columns: ["json_data"],
    columnPaths: ["json_data.sensor.temp"],
});

// Simple query
data, err := ifl.GetHistory(ctx, "sensordata", &ironflock.TableQueryParams{Limit: 100})
if err != nil {
	return err
}
 
// Query with time range and filters
data, err = ifl.GetHistory(ctx, "sensordata", &ironflock.TableQueryParams{
	Limit:  500,
	Offset: 0,
	TimeRange: ironflock.Between(
		time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
		time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC),
	),
	FilterAnd: []ironflock.Filter{
		ironflock.Where("temperature", ">", 20),
		ironflock.Where("humidity", "<=", 80),
	},
})
 
// Current value(s) only: the Latest() marker returns the newest row per entity
current, err := ifl.GetHistory(ctx, "sensordata", &ironflock.TableQueryParams{
	Limit:     100,
	FilterAnd: []ironflock.Filter{ironflock.Latest()},
})
 
// One field of a large json column: the column comes back pruned to its paths
readings, err := ifl.GetHistory(ctx, "sensordata", &ironflock.TableQueryParams{
	Limit:       100,
	Columns:     []string{"json_data"},
	ColumnPaths: []string{"json_data.sensor.temp"},
})

Paramètres de requête :

Lorsque vous passez des paramètres de requête, limit est obligatoire ; sans aucun paramètre (nil en Go), getHistory lit les 10 lignes les plus récentes.

En Go, ce sont les champs Limit, Offset, TimeRange, FilterAnd, Columns et ColumnPaths de ironflock.TableQueryParams. TimeRange est un *ironflock.TimeRange{Start, End} : chaque borne est un time.Time, une chaîne ISO 8601, un nombre en millisecondes epoch, ou nil pour une borne ouverte (ironflock.Between, Since et Until en construisent un à partir de valeurs time.Time). FilterAnd est un []ironflock.Filter. Il n’existe pas d’ancienne forme objet.

Opérateurs de filtre : =, !=, <>, >, <, >=, <=, LIKE, ILIKE, NOT LIKE, NOT ILIKE, IN, NOT IN, IS NULL, IS NOT NULL. JavaScript exporte cette liste sous le nom SQL_OPERATORS ; en Go, ironflock.SQLOperators() la renvoie.

Chaque condition de filtre est un objet avec les clés column, operator et value — en Go, construit avec ironflock.Where(column, operator, value), ironflock.IsNull(column) et ironflock.IsNotNull(column). Les opérateurs sont reconnus quelle que soit la casse, les espaces qui les entourent sont ignorés, et ils sont envoyés sous la forme listée ci-dessus — la seule que le backend de données accepte —, de sorte que "like" part sous la forme "LIKE", y compris à l’intérieur des groupes. Un opérateur hors de cette liste est envoyé tel quel, avec un avertissement. IS NULL et IS NOT NULL ne prennent pas de value et sont le seul moyen de tester NULL : tout autre opérateur exclut une ligne dont la colonne est NULL, exactement comme en SQL. IN et NOT IN prennent une liste (une slice en Go). LIKE est sensible à la casse ; utilisez ILIKE pour une correspondance insensible à la casse.

Combiner avec OR. Les entrées de filterAnd sont combinées par AND. Une entrée de groupe combine ses propres entrées — conditions, marqueur latest ou autres groupes — avec un seul opérateur, "AND" ou "OR" :

# Rows that are not soft-deleted: deleted IS NULL OR deleted = false
"filterAnd": [
    {
        "combinator": "OR",
        "filters": [
            {"column": "deleted", "operator": "IS NULL"},
            {"column": "deleted", "operator": "=", "value": False},
        ],
    }
]

// Rows that are not soft-deleted: deleted IS NULL OR deleted = false
filterAnd: [
    {
        combinator: "OR",
        filters: [
            { column: "deleted", operator: "IS NULL" },
            { column: "deleted", operator: "=", value: false },
        ],
    },
]

// Rows that are not soft-deleted: deleted IS NULL OR deleted = false
q := &ironflock.TableQueryParams{
	Limit: 100,
	FilterAnd: []ironflock.Filter{
		ironflock.Or(
			ironflock.IsNull("deleted"),
			ironflock.Where("deleted", "=", false),
		),
	},
}

Un backend de données antérieur aux groupes (fleetdb avant v1.2.0) rejette cette forme au lieu d’en appliquer une partie : l’appel échoue donc de manière explicite au lieu de renvoyer silencieusement des lignes que le filtre exclut.

Lire les valeurs actuelles. Une entrée {"latest": true} dans filterAnd (ironflock.Latest() en Go) n’est pas une condition de filtre mais un changement de mode : le backend de données ne renvoie que la ligne la plus récente de chaque entité, dérivée en SQL à partir de la clé d’entité que la table déclare avec maintainLatestFlagFor. Une table sans clé d’entité renvoie son unique ligne la plus récente.

Les autres conditions se combinent au marqueur comme on peut s’y attendre : les conditions portant sur les colonnes de la clé d’entité restreignent quelles entités sont renvoyées, tandis que toutes les autres conditions et timeRange s’appliquent aux lignes les plus récentes obtenues. Ainsi, combiner {"latest": true} avec un filtre sur deleted masque les entités supprimées au lieu de faire remonter leur ligne précédente.

Les versions précédentes d’IronFlock stockaient une colonne latest_flag physique. Elle n’existe plus — un filtre hérité latest_flag = true est toujours accepté et traité comme le marqueur, mais le nouveau code doit utiliser {"latest": true}. Le marqueur latest n’est pas disponible dans getSeriesHistory.

Plages temporelles. Le backend de données lit une borne fournie sous forme de chaîne avec le Date de JavaScript ; écrivez donc une date ou une date-heure ISO 8601 (2026-07-01, 2026-07-01T12:30:15.250Z) et séparez la date et l’heure par T. Les SDK refusent un espace entre la date et l’heure pour les années 0 à 99, que Date interprète mal : "0001-01-01 00:00:00" — ce que donne str(datetime.min) en Python — serait lu comme 2001. Le SDK Python refuse aussi une chaîne que datetime.fromisoformat ne sait pas lire. Une heure sans fuseau est lue comme UTC. Une borne numérique est exprimée en millisecondes epoch et doit être finie : NaN et ±Infinity arriveraient au backend de données comme une borne ouverte et supprimeraient silencieusement le filtre temporel ; les SDK les refusent donc avant l’envoi. En Go, une borne time.Time est envoyée en RFC 3339 en UTC, et une borne sous forme de chaîne doit être l’une des formes ISO 8601 que Date lit correctement — une date, ou une date et une heure du jour avec un Z ou un décalage UTC facultatif (+02:00 ou +0200) ; les autres chaînes, comme le format de base 20260701T123000Z, un décalage en heures seulement ou un jour que le mois ne compte pas (2026-02-30), échouent avec ironflock.ErrInvalidArgument avant tout envoi.

Transforms. Un transform (une vue SQL d’un data template, voir Tables de transformation) se lit différemment d’une table. Le backend de données n’applique que limit — 3000 au maximum, une valeur supérieure est refusée avec URI_INVALID_LIMIT —, offset et filterAnd. Il ignore timeRange, columns, columnPaths et le marqueur latest, et abandonne un filtre portant sur une colonne que le transform ne déclare pas (un transform n’a pas de colonnes implicites tsp, device_key ou authid), ce qui élargit le résultat. Ses lignes arrivent dans l’ordre propre de la vue, inversé : vous n’obtenez les lignes les plus récentes, les plus anciennes en premier, que lorsque la vue trie les plus récentes en premier. Bornez la plage temporelle d’un transform dans son SQL.

Résultats volumineux. Un résultat trop volumineux pour un seul message du backend de données (8 Mio de JSON) arrive en fragments, que le SDK réassemble en mémoire : vous obtenez les lignes d’une seule lecture, dans le même ordre. Des fragments qui ne concordent pas — un fragment manquant ou dupliqué, ou un nombre de lignes différent du récapitulatif du backend de données — font échouer la lecture au lieu de renvoyer une partie des lignes. Une ligne unique de plus de 8 Mio, ou un résultat dépassant le garde-fou de 1 Gio du backend de données, est refusé avec URI_RESULT_TOO_LARGE : réduisez limit, resserrez timeRange, sélectionnez moins de columns ou élaguez avec columnPaths.

getSeriesHistory / get_series_history

Récupère des données de séries temporelles sous-échantillonnées d’une table de flotte : des colonnes agrégées par intervalle de temps (par ex. des moyennes horaires). Idéal pour les graphiques couvrant de longues périodes. Disponible pour les tables (pas pour les transforms), sur les backends de données à partir de fleetdb v1.0.58.

from datetime import datetime, timedelta, timezone
from ironflock import SeriesMetric
 
now = datetime.now(timezone.utc)
avg = SeriesMetric(ref="temperature", method="AVG")  # AVG, SUM, COUNT, MIN, MAX, FIRST, LAST
series = await ironflock.get_series_history("sensordata", {
    "metrics": [avg, {"ref": "humidity", "method": "MAX"}],
    "bucketMs": 3_600_000,  # one-hour buckets; omit to divide the range into `limit` buckets
    "limit": 24,            # the bucket budget, 1–10000
    "timeRange": [(now - timedelta(hours=24)).isoformat(), now.isoformat()],  # required, with a start
    "groupBy": ["device_key"],
})
for row in series:
    print(row["tsp"], row["device_key"], row[avg.column])  # avg.column is "AVG:temperature"

import { seriesColumn } from "ironflock";
 
const end = Date.now();
const avg = { ref: "temperature", method: "AVG" }; // AVG, SUM, COUNT, MIN, MAX, FIRST, LAST
const series = await ironflock.getSeriesHistory("sensordata", {
    metrics: [avg, { ref: "humidity", method: "MAX" }],
    bucketMs: 3_600_000,                     // one-hour buckets; omit to divide the range into `limit` buckets
    limit: 24,                               // the bucket budget, 1–10000
    timeRange: [end - 24 * 3_600_000, end],  // required, with a start
    groupBy: ["device_key"],
});
for (const row of series) {
    console.log(row.tsp, row.device_key, row[seriesColumn(avg)]); // seriesColumn(avg) is "AVG:temperature"
}

now := time.Now()
avg := ironflock.SeriesMetric{Ref: "temperature", Method: ironflock.MethodAvg} // MethodAvg, MethodSum, MethodCount, MethodMin, MethodMax, MethodFirst, MethodLast
series, err := ifl.GetSeriesHistory(ctx, "sensordata", ironflock.SeriesQueryParams{
	Metrics:   []ironflock.SeriesMetric{avg, {Ref: "humidity", Method: ironflock.MethodMax}},
	Bucket:    time.Hour,                                      // one-hour buckets; 0 divides the range into Limit buckets
	Limit:     24,                                             // the bucket budget, 1–10000
	TimeRange: ironflock.Between(now.Add(-24*time.Hour), now), // required, with a start
	GroupBy:   []string{"device_key"},
})
if err != nil {
	return err
}
for _, row := range series {
	log.Println(row["tsp"], row["device_key"], row[avg.Column()]) // avg.Column() is "AVG:temperature"
}

Paramètres de requête :

Lignes. Chaque ligne correspond à un intervalle — d’un groupe, avec groupBy. tsp est le début de l’intervalle en millisecondes epoch, chaque colonne de groupBy revient sous son propre nom, et chaque métrique sous "<METHOD>:<ref>" (SeriesMetric.column en Python, seriesColumn(metric) en JavaScript, SeriesMetric.Column() en Go), par ex. row["AVG:temperature"]. Les lignes sont triées par tsp croissant ; un intervalle sans lignes est absent (pas de comblement des trous). AVG et SUM acceptent des colonnes numériques, MIN et MAX aussi des chaînes et des horodatages ; FIRST et LAST donnent la valeur de la ligne la plus ancienne et de la plus récente de l’intervalle ; COUNT compte les valeurs non nulles (pour tsp : les lignes). Un résultat volumineux est réassemblé à partir de fragments, comme pour getHistory.

Intervalles et fin ouverte. limit compte des intervalles, pas des lignes. Sans bucketMs, la plage temporelle est divisée en limit intervalles. Avec bucketMs, le backend de données élargit les intervalles à un multiple de bucketMs lorsque la plage en contient plus que limit — et une fin ouverte s’étend jusqu’au « maintenant » du backend de données, un peu après le vôtre. Les dernières 24 heures avec une fin ouverte contiennent 25 intervalles d’une heure, si bien que limit: 24 donne des intervalles de deux heures. Bornez la fin, comme dans l’exemple, ou prévoyez un intervalle de plus : avec bucketMs et une fin ouverte, limit + 1 intervalles peuvent revenir.

Les SDK vérifient avant l’envoi ce que le backend de données refuserait : au moins une métrique, des refs non vides, des méthodes connues, des noms de colonnes de 63 octets au plus, un début, une fin postérieure au début, et bucketMs sous forme d’entier d’au moins 1000 (en Go, un Bucket d’au moins 1 seconde, en millisecondes entières). Le backend de données refuse ce à quoi il ne peut pas répondre avec URI_INVALID_TIME_RANGE, URI_INVALID_METRIC, URI_INVALID_GROUP_BY ou URI_SERIES_TOO_MANY_GROUPS (plus de 50 000 lignes) — voir Refus du backend de données.

Forme obsolète. Les versions du SDK jusqu’à 1.9.0 envoyaient metrics sous forme de noms de colonnes plus un method de premier niveau ({"metrics": ["temperature"], "method": "AVG", ...}), ce que les backends de données refusent depuis fleetdb v1.0.58. Cette forme fonctionne toujours : le SDK envoie une métrique {ref, method} par colonne, émet un avertissement (un DeprecationWarning en Python, un avertissement console une fois par processus en JavaScript) et renomme les colonnes du résultat d’après les noms de colonnes, de sorte que l’ancien code continue de lire row["temperature"] — sauf si la ligne possède déjà une colonne de ce nom, comme tsp pour un COUNT de tsp. Passez aux métriques {ref, method} et lisez row["AVG:temperature"]. Le SDK Go ne connaît que la forme actuelle : une méthode par métrique (SeriesMetric).

S’abonner aux données

subscribeToTable / subscribe_to_table

S’abonne aux mises à jour en temps réel d’une table de flotte. Le gestionnaire est appelé chaque fois que le backend de données stocke une nouvelle ligne, avec comme premier argument la ligne telle qu’elle a été stockée — valeurs typées selon les colonnes du data template, colonnes secrètes masquées. Les lignes écrites via le chemin d’insertion en masse (publishRowsToTable / appendRowsToTable) sont transmises à votre gestionnaire une à la fois, de sorte que le code du gestionnaire reste identique quelle que soit la manière dont les données ont été écrites.

def on_sensor_data(*args, **kwargs):
    row = args[0]
    print("New reading:", row["tsp"], row["temperature"])
 
await ironflock.subscribe_to_table("sensordata", on_sensor_data)

// The handler is called with (args, kwargs, details); the row is args[0]
function onSensorData(args) {
    const row = args[0];
    console.log("New reading:", row.tsp, row.temperature);
}
 
await ironflock.subscribeToTable("sensordata", onSensorData);

// The handler gets an *ironflock.Event; ev.Row() is the row (ev.Args[0])
ts, err := ifl.SubscribeToTable(ctx, "sensordata", func(ev *ironflock.Event) {
	row := ev.Row()
	log.Println("New reading:", row["tsp"], row["temperature"])
})
if err != nil {
	return err
}
defer ts.Unsubscribe(ctx) // removes both feeds and ends the catch-up

subscribeToTable / subscribe_to_table renvoie un TableSubscription, le handle de ses deux flux : son unsubscribe() les retire et met fin au rattrapage décrit ci-dessous (voir unsubscribe / unregister).

Les lignes stockées pendant la coupure de la connexion arrivent après la reconnexion. Le routeur ne rejoue pas ce qui a été publié pendant que la connexion était coupée : après chaque reconnexion, le SDK lit donc les lignes stockées entre-temps et les transmet à votre gestionnaire, de la plus ancienne à la plus récente, avant les lignes qui arrivent en direct. Il s’agit de toutes les lignes dont le tsp est postérieur à celui de la ligne la plus récente reçue par votre gestionnaire. Tant que celui-ci n’a reçu aucune ligne, le point de départ est la ligne la plus récente stockée au moment de l’abonnement : le SDK la lit juste après l’abonnement et, si cette lecture échoue, part de l’instant de l’abonnement (selon l’horloge de l’appareil) ; une table alors vide est lue depuis son début. Une ligne écrite entre-temps avec un tsp plus ancien (par exemple une mesure mise en mémoire tampon qu’un appareil envoie plus tard) n’est pas rattrapée. Un rattrapage transmet au plus les 10 000 lignes les plus récentes et journalise un avertissement lorsqu’il en a lu autant. La lecture de rattrapage attend le backend de données comme toute lecture d’historique, au plus pendant la fenêtre de reconnexion, et les lignes en direct attendent qu’elle se termine ; si elle échoue, les lignes stockées entre-temps ne sont pas transmises et un avertissement est journalisé. Les lignes rattrapées proviennent d’une lecture, et non d’événements : le gestionnaire reçoit donc chacune d’elles sans les détails de l’événement — en Python la ligne seule, en JavaScript ([row], {}), en Go un Event avec Topic et Args, distribué dans l’ordre sur le DeliveryGroup de l’abonnement. Le rattrapage fait partie du SDK à partir de la version 1.10.0.

Un transform n’a pas de lignes propres : à chaque déclenchement de sa planification, le backend de données publie la vue entière — 3000 lignes au maximum, dans l’ordre inverse de la vue — sous la forme d’un seul événement dont le premier argument est la liste des lignes. Un transform n’a pas besoin de rattrapage : son prochain déclenchement après une reconnexion publie de nouveau la vue entière. event_rows(args[0]) en Python, eventRows(args) en JavaScript et ev.Rows() en Go lisent les deux formes : la ligne d’une table donne [row], la liste d’un transform la liste elle-même ([] pour une vue vide), et tout le reste None / undefined / nil. En Go, ev.Row() vaut nil pour l’événement d’un transform.

from ironflock import event_rows
 
def on_hourly(*args, **kwargs):
    for row in event_rows(args[0]) or []:
        print(row)
 
await ironflock.subscribe_to_table("hourly_averages", on_hourly)

import { eventRows } from "ironflock";
 
await ironflock.subscribeToTable("hourly_averages", (args) => {
    for (const row of eventRows(args) ?? []) console.log(row);
});

_, err := ifl.SubscribeToTable(ctx, "hourly_averages", func(ev *ironflock.Event) {
	for _, row := range ev.Rows() {
		log.Println(row)
	}
})
if err != nil {
	return err
}

subscribe

S’abonne à un topic WAMP qui vous est propre pour de la messagerie en temps réel personnalisée. Pour les lignes de table, utilisez subscribeToTable / subscribe_to_table : le routeur refuse les abonnements aux topics bruts d’écriture des tables (voir URI autorisées pour une app).

def on_alert(*args, **kwargs):
    print("Alert received:", args, kwargs)
 
alerts = await ironflock.subscribe("com.myapp.alerts", on_alert)
 
# Later: the handler is called for no further event
await alerts.unsubscribe()

function onAlert(...args) {
    console.log("Alert received:", args);
}
 
const alerts = await ironflock.subscribe("com.myapp.alerts", onAlert);
 
// Later: the handler is called for no further event
await alerts.unsubscribe();

sub, err := ifl.Subscribe(ctx, "com.myapp.alerts", func(ev *ironflock.Event) {
	log.Println("Alert received:", ev.Args, ev.Kwargs)
})
if err != nil {
	return err
}
defer ifl.Unsubscribe(ctx, sub) // or sub.Unsubscribe(ctx): the handler is called for no further event

subscribe renvoie un Subscription, le handle de l’abonnement (voir unsubscribe / unregister). Chaque appel renvoie son propre handle, y compris pour un topic qui fait déjà l’objet d’un abonnement.

Sans connexion, subscribe attend une connexion au plus pendant la fenêtre de reconnexion (60 secondes par défaut), comme publish, et subscribeToTable / subscribe_to_table fait de même (voir Fiabilité de la connexion).

La correspondance du topic est exacte. Des options d’abonnement, un argument facultatif placé après le gestionnaire, permettent de changer cela : un match valant "prefix" abonne à tous les topics qui commencent par celui indiqué. En Python, les options sont les SubscribeOptions d’autobahn (SubscribeOptions(match="prefix"), importées de autobahn.wamp.types), en JavaScript un objet ({ match: "prefix" }), et en Go ironflock.SubscribeOptions{Match: "prefix"}. L’abonnement est restauré avec les mêmes options après chaque reconnexion. subscribeToTable / subscribe_to_table accepte les mêmes options et les applique à ses deux flux.

unsubscribe / unregister

subscribe, subscribeToTable / subscribe_to_table et registerDeviceFunction / register_device_function renvoient chacun un handle. Un handle reste valide d’une reconnexion à l’autre jusqu’à ce que vous le retiriez : le SDK restaure ce qu’il représente après chaque reconnexion.

topic, table et procedure désignent ce que représente le handle ; procedure est l’URI WAMP complète. active indique si l’abonnement ou l’enregistrement est actuellement actif auprès du routeur : il vaut false tant que la connexion est coupée, après une restauration qui a échoué jusqu’à ce qu’une nouvelle tentative réussisse, et dès que le handle est retiré. Un TableSubscription est actif tant que ses deux flux le sont. ironflock.unsubscribe(handle) accepte un Subscription ou un TableSubscription, et ironflock.unregister(registration) un Registration ; chacune fait la même chose que la méthode du handle lui-même.

status = await ironflock.subscribe("com.myapp.status", on_status)
readings = await ironflock.subscribe_to_table("sensordata", on_row)
add = await ironflock.register_device_function("com.myapp.add", add_numbers)
 
print(readings.table, readings.active)  # sensordata True
 
await status.unsubscribe()             # the same as: await ironflock.unsubscribe(status)
await ironflock.unsubscribe(readings)  # both feeds of the table, and its catch-up
await ironflock.unregister(add)        # the same as: await add.unregister()

const status = await ironflock.subscribe("com.myapp.status", onStatus);
const readings = await ironflock.subscribeToTable("sensordata", onRow);
const add = await ironflock.registerDeviceFunction("com.myapp.add", addNumbers);
 
console.log(readings.table, readings.active); // sensordata true
 
await status.unsubscribe();            // the same as: await ironflock.unsubscribe(status)
await ironflock.unsubscribe(readings); // both feeds of the table, and its catch-up
await ironflock.unregister(add);       // the same as: await add.unregister()

status, err := ifl.Subscribe(ctx, "com.myapp.status", onStatus)
if err != nil {
	return err
}
readings, err := ifl.SubscribeToTable(ctx, "sensordata", onRow)
if err != nil {
	return err
}
add, err := ifl.RegisterDeviceFunction(ctx, "com.myapp.add", addNumbers)
if err != nil {
	return err
}
 
log.Println(readings.Table(), readings.Active()) // sensordata true
 
if err := status.Unsubscribe(ctx); err != nil { // the same as: ifl.Unsubscribe(ctx, status)
	log.Print(err)
}
if err := ifl.Unsubscribe(ctx, readings); err != nil { // both feeds of the table, and its catch-up
	log.Print(err)
}
if err := ifl.Unregister(ctx, add); err != nil { // the same as: add.Unregister(ctx)
	log.Print(err)
}

Un retrait obéit aux mêmes règles dans les trois SDK :

• Il prend effet immédiatement. Le gestionnaire n’est plus appelé pour aucun événement : ni pour un événement encore en file d’attente, ni pour les lignes restantes d’une insertion en masse, ni pour les lignes qu’un rattrapage transmettrait. Une fonction retirée n’est plus appelée ; un appel que le routeur lui achemine encore avant d’avoir supprimé l’enregistrement est refusé avec wamp.error.no_such_procedure. Un appel déjà en cours n’est pas attendu : un gestionnaire peut donc retirer son propre abonnement. Ce que vous retirez n’est jamais restauré après une reconnexion.
• Il n’attend pas de connexion. Tant que la connexion est coupée, l’abonnement ou l’enregistrement est retiré localement, car le routeur l’a supprimé avec la session, et l’appel rend la main immédiatement. Tant que la connexion est établie, le routeur en est informé, et l’appel se termine dès que le routeur a répondu. Un refus est levé (Python, une RuntimeError), lancé (JavaScript, une WampError) ou renvoyé (Go), mais le retrait est maintenu malgré tout.
• Il est idempotent. Un second appel ne fait rien, pas plus qu’un appel sans handle (None, null ou undefined, nil). Après stop() / Stop, un appel ne retire l’abonnement ou l’enregistrement que localement : en Python et en JavaScript, le start() suivant ne le restaure alors pas.
• Les handles sont indépendants. Retirer un handle ne retire jamais le gestionnaire d’un autre, même sur le même topic ou la même table. L’abonnement auprès du routeur prend fin avec le dernier handle de son topic.
• Un TableSubscription retire ses deux flux, transformed.<table> et transformed.bulk.<table>, et met fin à son rattrapage.

Migration : avant la version 1.10.0, les SDK Python et JavaScript renvoyaient les objets d’abonnement et d’enregistrement d’autobahn, et subscribe_to_table / subscribeToTable ne renvoyait que l’abonnement au flux des lignes : le retirer laissait donc en place l’abonnement au flux des insertions en masse. Le code qui appelle unsubscribe() ou unregister() sur la valeur renvoyée continue de fonctionner, et ce qu’il retire n’est plus restauré après une reconnexion. Les autres membres des objets d’autobahn, comme id, ont disparu.

Colonnes secrètes

Une colonne déclarée secret: true dans le data-template de l’application est chiffrée au repos. Aucun chemin de lecture ordinaire ne renvoie la valeur en clair, pas même à l’application qui l’a écrite :

NULL est transmis tel quel — NULL — sur tous les chemins, de sorte que « défini mais masqué » reste distinguable de « jamais écrit ».

Sur une table d’entités, le cycle lecture-modification-écriture est sûr : republier une ligne qui porte encore l’espace réservé __secret__ — ou omettre complètement la colonne secrète — conserve le secret stocké au lieu de l’écraser, et un null explicite l’efface. Voir Colonnes secrètes dans le guide du backend de données pour les règles exactes.

Seule une colonne string peut être secrète, et ni tsp ni une clé d’entité ne peuvent l’être. Le backend de données chiffre chaque valeur avec AES-256-GCM et un IV aléatoire qui lui est propre, si bien que le même secret est stocké sous un texte chiffré différent dans chaque ligne : une colonne secrète ne peut être ni filtrée, ni regroupée, ni triée. Un filtre sur une telle colonne est refusé avec URI_SECRET_COLUMN ; pour tester une valeur, utilisez verifySecret.

from datetime import datetime, timezone
 
# Written like any other column — the data backend encrypts it on insert
await ironflock.publish_to_table("credentials", {
    "tsp": datetime.now(timezone.utc).isoformat(),
    "device_id": "d-1",
    "api_token": "hunter2",
})
 
# A normal read redacts it
rows = await ironflock.getHistory("credentials", {"limit": 1})
# [{"tsp": "...", "device_id": "d-1", "api_token": "__secret__"}]

// Written like any other column — the data backend encrypts it on insert
await ironflock.publishToTable("credentials", [
    { tsp: new Date().toISOString(), device_id: "d-1", api_token: "hunter2" },
]);
 
// A normal read redacts it
const rows = await ironflock.getHistory("credentials", { limit: 1 });
// [{ tsp: "...", device_id: "d-1", api_token: "__secret__" }]

// Written like any other column — the data backend encrypts it on insert
err := ifl.PublishToTable(ctx, "credentials", ironflock.Row{
	"tsp":       time.Now(),
	"device_id": "d-1",
	"api_token": "hunter2",
})
if err != nil {
	return err
}
 
// A normal read redacts it
rows, err := ifl.GetHistory(ctx, "credentials", &ironflock.TableQueryParams{Limit: 1})
// [map[api_token:__secret__ device_id:d-1 tsp:...]]

Les deux fonctions ci-dessous ne sont appelables que depuis les conteneurs de l’application elle-même. Le routeur de messages les refuse à tous les rôles navigateur ainsi qu’aux apps consommatrices, ce qui explique qu’un handle ConsumedApp n’ait pas d’équivalent : les colonnes secrètes d’une autre app arrivent masquées et le restent.

revealSecrets / reveal_secrets

Lit les lignes de l’une de vos propres tables avec ses colonnes secrètes déchiffrées.

rows = await ironflock.reveal_secrets("credentials", {
    "limit": 1,
    "filterAnd": [{"column": "device_id", "operator": "=", "value": "d-1"}],
})
# [{"tsp": "...", "device_id": "d-1", "api_token": "hunter2"}]

const rows = await ironflock.revealSecrets("credentials", {
    limit: 1,
    filterAnd: [{ column: "device_id", operator: "=", value: "d-1" }],
});
// [{ tsp: "...", device_id: "d-1", api_token: "hunter2" }]

rows, err := ifl.RevealSecrets(ctx, "credentials", &ironflock.TableQueryParams{
	Limit:     1,
	FilterAnd: []ironflock.Filter{ironflock.Where("device_id", "=", "d-1")},
})
if err != nil {
	return err
}
// [map[api_token:hunter2 device_id:d-1 tsp:...]]

Les paramètres de requête sont les mêmes que ceux de getHistory, à ceci près que limit ne peut pas dépasser 100. Ce plafond existe pour empêcher qu’un seul appel déchiffre une table entière, et le backend de données rejette une valeur supérieure au lieu de la ramener silencieusement à la limite. Sans paramètres de requête, l’appel lit les 10 lignes les plus récentes. Contrairement à getHistory, il renvoie les lignes de la plus récente à la plus ancienne.

Le backend de données répond au plus à 30 révélations par minute par identifiant d’app sur un appareil ; au-delà, l’appel échoue avec URI_RATE_LIMITED. Révélez un secret une fois et conservez-le, plutôt qu’à chaque utilisation. Un filtre sur une colonne secrète est refusé avec URI_SECRET_COLUMN. Le backend de données ne sert cette fonction que pour les tables qui déclarent une colonne secrète : pour toute autre table, le routeur répond wamp.error.no_such_procedure ; le SDK réessaie alors pendant toute la fenêtre de reconnexion, puis l’appel échoue avec une erreur indiquant que la procédure n’est pas enregistrée. L’erreur indique les causes possibles, en commençant par la plus probable : la table ne déclare aucune colonne secrète (secret: true dans le data template), la table n’est pas déclarée, ou le backend de données est antérieur aux colonnes secrètes.

verifySecret / verify_secret

Vérifie une valeur candidate par rapport à une colonne secrète sans la révéler — l’équivalent « vérification de mot de passe » de la fonction de révélation. La comparaison s’exécute à l’intérieur du backend de données, en temps constant, et seule la réponse est renvoyée.

ok = await ironflock.verify_secret(
    "credentials", "api_token", submitted_token,
    {"limit": 1, "filterAnd": [{"column": "device_id", "operator": "=", "value": "d-1"}]},
)
if ok:
    ...

const { match, checked } = await ironflock.verifySecret(
    "credentials", "api_token", submittedToken,
    { limit: 1, filterAnd: [{ column: "device_id", operator: "=", value: "d-1" }] },
);
 
if (checked === 0) {
    // No row matched the selector at all — an unknown device, not a wrong token
}

res, err := ifl.VerifySecret(ctx, "credentials", "api_token", submittedToken, &ironflock.TableQueryParams{
	Limit:     1,
	FilterAnd: []ironflock.Filter{ironflock.Where("device_id", "=", "d-1")},
})
if err != nil {
	return err
}
if res.Checked == 0 {
	// No row matched the selector at all — an unknown device, not a wrong token
}
if res.Match {
	// ...
}

Paramètres :

En Go, les paramètres sont des chaînes positionnelles placées après le contexte, et la requête est un *ironflock.TableQueryParams (nil pour la ligne la plus récente).

JavaScript renvoie { match, checked } et Go un *ironflock.SecretVerifyResult avec Match et Checked ; Python renvoie un simple bool. Lorsque vous disposez de checked, il vaut la peine de l’utiliser : il distingue une valeur candidate erronée (checked > 0) d’un sélecteur qui n’a trouvé aucune ligne (checked === 0), deux défaillances très différentes à signaler à un utilisateur.

Comme chaque ligne est chiffrée avec sa propre valeur aléatoire, deux lignes contenant le même secret stockent un texte chiffré différent. C’est pourquoi un filtre = sur une colonne secrète ne peut pas fonctionner — le backend de données refuse tout filtre sur une telle colonne avec URI_SECRET_COLUMN — et que cette fonction existe à la place.

Le backend de données répond au plus à 120 vérifications par minute par identifiant d’app sur un appareil ; au-delà, l’appel échoue avec URI_RATE_LIMITED. Pour une vérification à chaque requête (une clé d’API, par exemple), mettez brièvement en cache un résultat positif. Une colonne qui n’est pas une colonne secrète est refusée avec URI_NOT_A_SECRET_COLUMN ; sur une table sans aucune colonne secrète, l’appel échoue de la même manière que revealSecrets / reveal_secrets sur cette table.

Accès aux données inter-apps

Lisez les données de flotte d’une autre app depuis votre propre app, au sein du même projet. Votre app doit déclarer l’app fournisseur dans la section consumes: de son propre data-template.yml (ou détenir l’autorisation wildcard, voir plus bas), et l’utilisateur du projet doit accorder l’accès. L’accès est en lecture seule : vous pouvez interroger l’historique et vous abonner en temps réel aux lignes des tables et des transforms que le fournisseur partage, mais vous ne pouvez pas y écrire. Les connexions aux apps consommées sont mises en cache par app et par stage et fermées automatiquement lorsque votre instance s’arrête.

La connexion nécessite les identifiants propres à l’app que l’agent de l’appareil injecte (APP_AUTH_ID, APP_AUTH_SECRET). La plateforme refuse les anciens identifiants d’appareil — le repli sur le numéro de série d’une app qui n’a pas reçu d’identifiants propres, par ex. sous un agent de l’appareil plus ancien — sur le realm d’une autre app (NOT_AUTHORIZED, avec un message qui le précise), sauf si l’app fournisseur s’exécute sur le même appareil : la connexion rejoint alors son realm avec les pleins droits de cette app, et non en lecture seule.

Si votre app détient l’autorisation wildcard (consumes: [{ app: "*" }]), vous pouvez découvrir et ouvrir dynamiquement les fournisseurs avec listConsumableApps / list_consumable_apps et connectToAllApps / connect_to_all_apps (ci-dessous).

connectToApp / connect_to_app

Ouvre une connexion en lecture seule au backend de données d’une autre app et renvoie un handle. Le handle expose getHistory / get_history, subscribeToTable / subscribe_to_table et getSeriesHistory / get_series_history (tables uniquement) — les mêmes interrogations et abonnements que vous utilisez sur vos propres tables, avec les mêmes paramètres et résultats — ainsi que close et les catalogues partagés tables / transforms. Son subscribeToTable / subscribe_to_table renvoie le même handle TableSubscription que pour vos propres tables, que ironflock.unsubscribe accepte également (voir unsubscribe / unregister), et ses abonnements aux tables font l’objet du même rattrapage après une reconnexion (voir subscribeToTable).

Le handle porte aussi le nom et le stage du fournisseur (app et stage, en Go App et Stage), ainsi que sa connexion au realm du fournisseur : is_connected / isConnected / IsConnected() indique si elle est ouverte, connection / Connection() est la connexion elle-même. En JavaScript, close() se résout une fois la connexion fermée, en 5 secondes au plus.

# Open a read-only handle on another app's data backend
weather = await ironflock.connect_to_app("weather-app")
 
# Inspect what the provider shares
print([t["tablename"] for t in weather.tables])
 
# Query history and subscribe, just like your own tables
rows = await weather.get_history("forecasts", {"limit": 100})
 
def on_forecast(*args, **kwargs):
    print("New forecast:", args)
 
await weather.subscribe_to_table("forecasts", on_forecast)

// Open a read-only handle on another app's data backend
const weather = await ironflock.connectToApp("weather-app");
 
// Inspect what the provider shares
console.log(weather.tables.map((t) => t.tablename));
 
// Query history and subscribe, just like your own tables
const rows = await weather.getHistory("forecasts", { limit: 100 });
 
await weather.subscribeToTable("forecasts", (...args) => {
    console.log("New forecast:", args);
});

// Open a read-only handle on another app's data backend
weather, err := ifl.ConnectToApp(ctx, "weather-app")
var cerr *ironflock.CrossAppAccessError
if errors.As(err, &cerr) {
	return fmt.Errorf("no access to weather-app (%s): %w", cerr.Code, err) // e.g. NO_GRANT
} else if err != nil {
	return err
}
 
// Inspect what the provider shares
for _, t := range weather.Tables {
	log.Println(t.Tablename)
}
 
// Query history and subscribe, just like your own tables
rows, err := weather.GetHistory(ctx, "forecasts", &ironflock.TableQueryParams{Limit: 100})
if err != nil {
	return err
}
 
_, err = weather.SubscribeToTable(ctx, "forecasts", func(ev *ironflock.Event) {
	log.Println("New forecast:", ev.Row())
})

Paramètres :

Si l’accès est refusé ou mal utilisé, un CrossAppAccessError est levé (Python) / lancé (JavaScript) / renvoyé (Go, un *ironflock.CrossAppAccessError à tester avec errors.As) avec un champ code (Code en Go, avec des constantes comme ironflock.CodeNoGrant) : NO_GRANT, PROVIDER_NOT_INSTALLED, UNKNOWN_APP, PRIVATE_TABLE, SECRET_COLUMN (une requête qui filtre — y compris à l’intérieur d’un groupe — ou sélectionne une colonne que le fournisseur marque comme secrète) ou NOT_AUTHORIZED (l’autorisation a été révoquée ou n’a pas pu être vérifiée à ce moment-là — ou votre app a présenté les anciens identifiants d’appareil, auquel cas le message le précise). Un subscribeToTable / subscribe_to_table d’une app consommée que le routeur du fournisseur refuse (wamp.error.not_authorized, wamp.error.authorization_failed ou wamp.error.authentication_failed) échoue lui aussi avec un CrossAppAccessError portant NOT_AUTHORIZED, comme une lecture refusée.

Un refus pendant que connectToApp / connect_to_app attend fait échouer l’appel immédiatement. Une fois un handle ouvert, un refus n’est considéré comme définitif que s’il persiste — 3 refus ou plus depuis la dernière fois que la connexion était établie (la fermeture de la session par le routeur pour une raison d’authentification compte pour un, de même que chaque reconnexion refusée), le premier remontant à au moins 60 secondes —, car la plateforme refuse de la même manière lorsqu’elle ne peut brièvement pas vérifier l’accès. D’ici là, le handle continue de se reconnecter et se rétablit si une reconnexion réussit. Une fois le refus définitif, on_error / onError / OnError est appelé et le handle est évincé : le prochain connectToApp / connect_to_app / ConnectToApp ouvre une nouvelle connexion. À partir de là, les lectures et les abonnements du handle échouent immédiatement, avec l’erreur transmise à on_error / onError — en Go, avec une erreur qui enveloppe wamp.ErrStopped.

En Python, stage et on_error sont des arguments nommés ; en JavaScript, ils sont passés via un objet d’options (connectToApp(appName, { stage, onError })) ; en Go, via une struct (ConnectToApp(ctx, appName, ironflock.ConnectToAppOptions{Stage, OnError})), où OnError est une func(*ironflock.CrossAppAccessError). En Go, ctx ne borne que l’attente de l’appelant : les appels simultanés pour la même app partagent une seule tentative, et Close(ctx) ferme un handle. Go compare les noms d’app sans tenir compte de la casse, et ConsumedApp.Stage est le stage en minuscules ("dev" ou "prod"), contrairement à ifl.Stage().

listConsumableApps / list_consumable_apps

Liste chaque fournisseur non privé du projet — la primitive de découverte pour les apps qui détiennent l’autorisation de consommation wildcard (consumes: [{ app: "*" }] dans votre data-template.yml, accordée par l’utilisateur du projet). Elle effectue un seul appel et n’ouvre aucune connexion : affichez les catalogues renvoyés dans un sélecteur, puis appelez connectToApp / connect_to_app pour ceux que vous souhaitez — ou connectToAllApps / connect_to_all_apps pour tous les ouvrir en une seule fois.

Remarque : Déclarez l’autorisation dans le data-template.yml de votre app, et mettez le * entre guillemets — un * nu est un alias YAML et ne sera pas analysé :

consumes:
  - app: "*"

providers = await ironflock.list_consumable_apps()
 
for p in providers:
    print(p["app"], list(p["stages"].keys()))  # e.g. "weather-app" ["dev", "prod"]

const providers = await ironflock.listConsumableApps();
 
for (const p of providers) {
    console.log(p.app, Object.keys(p.stages)); // e.g. "weather-app" ["dev", "prod"]
}

providers, err := ifl.ListConsumableApps(ctx)
if err != nil {
	return err
}
 
for _, p := range providers {
	log.Println(p.App, p.Stages.Dev != nil, p.Stages.Prod != nil) // e.g. weather-app true true
	if c := p.Catalog("prod"); c != nil {
		log.Println(len(c.Tables), "shared tables")
	}
}

Chaque entrée décrit un fournisseur :

En Go, chaque entrée est un ironflock.ConsumedAppInfo avec App, ProviderAppKey et Stages.Dev / Stages.Prod (un *StageCatalog avec Tables et Transforms, nil pour un stage absent) ; Catalog(stage) en renvoie un par son nom.

Lève (Python) / lance (JavaScript) / renvoie (Go) un CrossAppAccessError avec code: NO_GRANT si votre app ne détient aucune autorisation wildcard.

connectToAllApps / connect_to_all_apps

Ouvre des handles en lecture seule vers chaque fournisseur non privé du projet en un seul appel (consommateurs wildcard uniquement). Énumère les fournisseurs via listConsumableApps / list_consumable_apps et ouvre chacun d’eux, en ignorant ceux qui n’ont pas de backend de données pour le stage demandé. Chaque handle est mis en cache sous la même clé que connectToApp / connect_to_app, de sorte qu’un connectToApp(name) ultérieur renvoie le handle déjà préchauffé. Les handles renvoyés sont fermés ensemble lorsque votre instance s’arrête.

apps = await ironflock.connect_to_all_apps(
    on_error=lambda err: print("Provider skipped:", err)
)
 
for app in apps:
    rows = await app.get_history(app.tables[0]["tablename"], {"limit": 10})
    print(app.app, rows)

const apps = await ironflock.connectToAllApps({
    onError: (err) => console.warn("Provider skipped:", err),
});
 
for (const app of apps) {
    const rows = await app.getHistory(app.tables[0]?.tablename, { limit: 10 });
    console.log(app.app, rows);
}

apps, err := ifl.ConnectToAllApps(ctx, ironflock.ConnectToAllAppsOptions{
	OnError: func(err error) { log.Println("Provider skipped:", err) },
})
if err != nil {
	return err
}
 
for _, app := range apps {
	if len(app.Tables) == 0 {
		continue
	}
	rows, err := app.GetHistory(ctx, app.Tables[0].Tablename, &ironflock.TableQueryParams{Limit: 10})
	if err != nil {
		return err
	}
	log.Println(app.App, rows)
}

Paramètres :

Renvoie les handles de fournisseurs ouverts avec succès (même type de handle que connectToApp / connect_to_app). Lève (Python) / lance (JavaScript) / renvoie (Go) un CrossAppAccessError avec code: NO_GRANT si votre app ne détient aucune autorisation wildcard.

En Python, stage, on_error et continue_on_error sont des arguments nommés ; en JavaScript, ils sont passés via un objet d’options (connectToAllApps({ stage, onError, continueOnError })) ; en Go, via une struct (ConnectToAllApps(ctx, ironflock.ConnectToAllAppsOptions{Stage, OnError, StopOnError})), où OnError est une func(error) et où StopOnError: true correspond à continueOnError: false.

Stockage de fichiers managé

Chaque backend de données d’app dispose, à côté de ses tables, d’un stockage d’objets privé accessible via la propriété files (ifl.Files() en Go, un *filestore.FileStore). La propriété n’effectue aucune E/S : dans les trois SDK, elle peut donc être lue avant le démarrage de la connexion. Utilisez-le pour des images, des PDF, des images de caméra, des blobs de firmware — tout ce qui n’a pas sa place dans une ligne de table. Aucune configuration n’est nécessaire : une app dépourvue de section files: dans son data-template obtient malgré tout un espace de noms nommé default (un template qui déclare ses propres espaces de noms le remplace — voir Espaces de noms).

Cette section est la référence côté client. Pour le côté plateforme — déclaration des espaces de noms, quotas et rétention, partage de fichiers entre apps, identifiants S3 par app et comportement sur les appliances sur site — voir Stockage de fichiers.

L’idée clé est que stocker un objet vous renvoie une URL permanente que vous pouvez écrire directement dans une colonne de table, de sorte qu’un widget de tableau de bord puisse l’afficher sans travail supplémentaire :

from datetime import datetime, timezone
 
# Store an object and get a permanent URL back in the same call
info = await ironflock.files.put("part-1.jpg", jpeg_bytes, content_type="image/jpeg")
 
# The URL is safe to store in a table column — a dashboard widget can then
# render <img src="{{photo_url}}"> without any extra round trip
await ironflock.publish_to_table("inspections", {
    "tsp": datetime.now(timezone.utc).isoformat(),
    "part_id": "1",
    "photo_url": info.url,
})
 
# Read it back
data = await ironflock.files.get("part-1.jpg")
 
# Every object in the folder 2026/, in its subfolders too (pages are fetched for you)
async for obj in ironflock.files.iter(prefix="2026/"):
    print(obj.key, obj.size)

// Store an object and get a permanent URL back in the same call
const info = await ironflock.files.put("part-1.jpg", jpegBytes, {
    contentType: "image/jpeg",
});
 
// The URL is safe to store in a table column — a dashboard widget can then
// render <img src="{{photo_url}}"> without any extra round trip
await ironflock.publishToTable("inspections", [
    { tsp: new Date().toISOString(), part_id: "1", photo_url: info.url },
]);
 
// Read it back
const data = await ironflock.files.get("part-1.jpg");
 
// Every object in the folder 2026/, in its subfolders too (pages are fetched for you)
for await (const obj of ironflock.files.iterate({ prefix: "2026/" })) {
    console.log(obj.key, obj.size);
}

files := ifl.Files()
 
// Store an object and get a permanent URL back in the same call
info, err := files.Put(ctx, "part-1.jpg", jpegBytes, filestore.ContentType("image/jpeg"))
if err != nil {
	return err
}
 
// The URL is safe to store in a table column — a dashboard widget can then
// render <img src="{{photo_url}}"> without any extra round trip
err = ifl.PublishToTable(ctx, "inspections", ironflock.Row{
	"tsp":       time.Now(),
	"part_id":   "1",
	"photo_url": info.URL,
})
 
// Read it back
data, err := files.Get(ctx, "part-1.jpg")
 
// Every object in the folder 2026/, in its subfolders too (pages are fetched for you)
for obj, err := range files.Iter(ctx, filestore.Prefix("2026/")) {
	if err != nil {
		return err
	}
	log.Println(obj.Key, obj.Size)
}

Cette URL n’expire jamais, mais ce n’est pas un lien public : elle ne reste lisible que par un demandeur authentifié disposant de l’accès READ sur ce backend de données, et un proxy d’authentification le vérifie à chaque requête, en gardant sa décision en cache pendant 5 minutes au plus. Elle peut donc être stockée sans risque dans la base de données.

Espaces de noms

Un espace de noms est un préfixe de clé porteur de règles — rétention, règles de partage, types de contenu autorisés. Ce n’est pas un bucket distinct ; tous les espaces de noms d’une app vivent dans l’unique zone de stockage de cette app. N’en déclarez un que lorsqu’un ensemble d’objets a besoin de règles différentes ; sinon, restez dans default et organisez vos objets avec des chemins de clés comme 2026/03/part-1.jpg.

Déclarez les espaces de noms dans data-template.yml. Dès que vous en déclarez, ils remplacent le default implicite : listez aussi un espace de noms nommé default, sinon chaque appel sans espace de noms échoue avec NO_SUCH_NAMESPACE.

files:
  # Storage budget the app suggests for itself. The project user can change it,
  # and their setting is the one that gets enforced.
  quotaBytes: 5368709120
  namespaces:
    # Keep default: declaring namespaces replaces the implicit one.
    - name: default
    - name: frames
      description: Raw camera frames, one JPEG per inspected part.
      contentTypes: ["image/jpeg"]
      maxObjectBytes: 20971520
      retention: { deleteAfter: 30 days }

Notez que le budget est déclaré une seule fois pour toute l’app, et non par espace de noms. Un espace de noms n’est qu’un préfixe de clé à l’intérieur de l’unique zone de stockage de l’app : il n’y a donc rien contre quoi un budget par préfixe pourrait être appliqué. maxObjectBytes, lui, est défini par espace de noms — il plafonne un objet unique, pas un total : 100 Mio s’il n’est pas défini, 5 Gio au maximum (OBJECT_TOO_LARGE au-delà).

Chaque méthode ci-dessous accepte l’espace de noms comme argument optionnel et utilise default par défaut ; un espace de noms vide ("") signifie aussi default.

Stocker et lire des objets

# Bytes in, bytes out
info = await ironflock.files.put("reports/march.pdf", pdf_bytes, content_type="application/pdf")
data = await ironflock.files.get("reports/march.pdf")
 
# Or straight from/to a local file — these stream on the large-object path,
# so a multi-gigabyte file never has to fit in memory
await ironflock.files.put_file("firmware/v2.bin", "/data/build/v2.bin")
await ironflock.files.get_to_file("firmware/v2.bin", "/tmp/v2.bin")

// Bytes in, bytes out — put/get work on Uint8Array in both Node and the browser
const info = await ironflock.files.put("reports/march.pdf", pdfBytes, {
    contentType: "application/pdf",
});
const data = await ironflock.files.get("reports/march.pdf");

files := ifl.Files()
 
// Bytes in, bytes out
info, err := files.Put(ctx, "reports/march.pdf", pdfBytes, filestore.ContentType("application/pdf"))
if err != nil {
	return err
}
data, err := files.Get(ctx, "reports/march.pdf")
 
// Or straight from/to a local file — these stream on the large-object path,
// so a multi-gigabyte file never has to fit in memory
_, err = files.PutFile(ctx, "firmware/v2.bin", "/data/build/v2.bin")
_, err = files.GetToFile(ctx, "firmware/v2.bin", "/tmp/v2.bin")
 
// Or from a reader / to a writer
_, err = files.PutReader(ctx, "logs/today.txt", logReader, logSize)
_, err = files.GetTo(ctx, "logs/today.txt", os.Stdout)

put et get gardent l’objet entier en mémoire. Pour un objet volumineux, utilisez les variantes pour fichiers, qui transfèrent en flux (en Go aussi PutReader et GetTo). JavaScript n’offre pas d’assistants de chemins de fichiers, car le paquet est livré en un seul build pour Node comme pour le navigateur — lisez et écrivez vous-même les fichiers locaux avec fs.

En Python, le travail sur les fichiers de put_file et get_to_file s’exécute hors de la boucle d’événements. get_to_file crée les répertoires parents manquants et écrit le fichier sur place dès que les premiers octets de l’objet sont disponibles : une lecture refusée (objet inexistant, non autorisé) laisse le chemin intact, tandis qu’une lecture qui échoue en cours de route laisse ce qui a été écrit jusque-là. Un FIFO est écrit au fil de l’arrivée de l’objet, et son ouverture attend un lecteur : un FIFO que personne ne lit bloque donc l’appel (pas la boucle d’événements) ; asyncio.wait_for permet d’y renoncer. put_file lit un FIFO jusqu’au bout avant de le stocker.

En Go, GetToFile crée lui aussi les répertoires parents manquants, mais télécharge dans un fichier temporaire à côté de la cible et le renomme à sa place une fois le téléchargement terminé : un téléchargement échoué ou annulé ne laisse jamais de fichier partiel et conserve le fichier précédent. Les liens symboliques sont suivis (le fichier vers lequel ils pointent est écrit, et les liens restent) ; le fichier de remplacement reçoit, dans la mesure où le processus le peut, le propriétaire, le groupe et les bits de permission de l’ancien fichier. Une FIFO ou un périphérique est écrit sur place au fil du flux de l’objet. Pour une cible à côté de laquelle aucun nouveau fichier ne peut être créé, par exemple sur un système de fichiers en lecture seule ou un pseudo-système de fichiers, utilisez GetTo avec un fichier que vous ouvrez vous-même.

put accepte : content_type / contentType (le type MIME ; l’espace de noms peut restreindre ceux qui sont autorisés) et namespace. En Python, ce sont des arguments nommés ; en JavaScript, ils sont passés dans un objet d’options ; en Go, ce sont des options (filestore.ContentType(…), filestore.Namespace(…)).

Lister et inspecter

Dossiers. Un préfixe qui se termine par / désigne un dossier : iter(prefix="2026/") / iterate({ prefix: "2026/" }) / Iter(ctx, filestore.Prefix("2026/")) renvoie 2026/a.txt et 2026/sub/c.txt, mais pas 2026-notes.txt. list ne peut pas ouvrir un dossier par son nom, car le service de fichiers refuse un préfixe de listage qui se termine par / (FleetFiles v0.2 répond INTERNAL) : list avec le préfixe 2026 renvoie 2026-notes.txt parmi les objets et le dossier 2026/ parmi les préfixes. Le service stocke les clés en forme de normalisation Unicode C ; donnez donc aussi un préfixe de dossier en NFC. Une itération qui rencontre une clé sous une autre forme du préfixe échoue au lieu d’ignorer toutes les clés.

Les objets sont décrits par les mêmes champs dans les trois SDK, selon le style de nommage propre à chaque langage : namespace, key, size, etag, content_type / contentType, last_modified / lastModified, checksum_sha256 / checksumSha256 et url — en Go, les champs Namespace, Key, Size, ETag, ContentType, LastModified, ChecksumSHA256 et URL de filestore.ObjectInfo.

Utilisation du stockage et quota

usage obtient sa réponse du magasin d’objets en un seul appel : les totaux sont donc exacts, et non additionnés par le SDK :

u = await ironflock.files.usage()
print(u.size_bytes, u.object_count, u.quota_bytes, u.free_bytes)
 
# Break the total down per namespace (costs one listing per namespace)
detailed = await ironflock.files.usage(detail=True)
print(detailed.per_namespace)   # {"default": 1048576, "frames": 73400320}

const u = await ironflock.files.usage();
console.log(u.sizeBytes, u.objectCount, u.quotaBytes, u.freeBytes);
 
// Break the total down per namespace (costs one listing per namespace)
const detailed = await ironflock.files.usage({ detail: true });
console.log(detailed.perNamespace);   // { default: 1048576, frames: 73400320 }

u, err := ifl.Files().Usage(ctx)
if err != nil {
	return err
}
log.Println(u.SizeBytes, u.ObjectCount, u.QuotaBytes, u.FreeBytes)
 
// Break the total down per namespace (costs one listing per namespace)
detailed, err := ifl.Files().Usage(ctx, filestore.Detail())
if err != nil {
	return err
}
log.Println(detailed.PerNamespace) // map[default:1048576 frames:73400320]

En Go, les champs sont SizeBytes, ObjectCount, QuotaBytes, FreeBytes et PerNamespace de filestore.StorageUsage.

La ventilation par espace de noms est désactivée par défaut, car le magasin ne sait pas y répondre directement : il comptabilise par zone de stockage, et un espace de noms n’est qu’un préfixe ; le SDK doit donc lister chaque espace de noms pour en additionner les tailles. Demandez-la quand vous en avez besoin, pas sur un chemin critique.

Deux quotas différents apparaissent, et il vaut la peine de ne pas les confondre. catalog() renvoie les deux :

En Go, Catalog(ctx) renvoie un *filestore.Catalog avec QuotaBytes et SuggestedQuotaBytes.

Ils diffèrent dès qu’un utilisateur a augmenté ou réduit le budget de l’app, et c’est précisément pourquoi la valeur appliquée est lue depuis le magasin plutôt que depuis le template — redéployer l’app ne doit pas réinitialiser silencieusement le choix d’un utilisateur. Une interface peut afficher les deux (« l’app suggère X, vous avez réglé Y »). L’application du quota s’appuie toujours sur la première valeur. L’utilisateur peut modifier le budget à tout moment, et catalog() le rapporte tel qu’il était lors de sa dernière récupération : lisez la valeur actuelle avec usage().

Partager des objets

Il existe deux types de liens, et la différence a son importance :

share_url / shareUrl est une capacité au porteur : remettez-la à une personne qui a besoin d’un accès temporaire, et ne la stockez pas dans la base de données. Utilisez url pour tout ce qu’affiche un tableau de bord.

url renvoie None / undefined / "" (Go) lorsque le déploiement n’a pas de frontal HTTP (par exemple une appliance en HTTP simple) — c’est le signal qu’il faut se rabattre sur get. Dans un espace de noms déclaré avec share: none, l’URL permanente ne fonctionne pas non plus, mais url ne peut pas le savoir, car le catalogue n’indique pas comment un espace de noms est partagé : il renvoie l’URL malgré tout, et le frontal de fichiers y répond par une erreur 404. Lisez ces objets avec get ; les liens de share_url / shareUrl / ShareURL ne dépendent pas de share. Passer l’etag d’un objet comme argument version (filestore.Version(etag) en Go) permet aux navigateurs de mettre la réponse en cache de façon immuable.

En Python et en Go, cloud_url(key, …) / CloudURL(ctx, key, …) renvoie l’URL permanente via le tunnel de fichiers cloud d’une appliance (https://i<instanceKey>-files.<cloud-edge>) : joignable depuis Internet tant que l’appliance est en ligne, avec la même autorisation que url. Elle renvoie None ("" en Go) sur les déploiements hébergés dans le cloud (où url est déjà joignable depuis Internet), là où il n’y a pas de frontal HTTP, et tant que le partage cloud du backend de données est désactivé. L’utilisateur peut le basculer à tout moment ; cloud_url / CloudURL relit donc le catalogue lorsque celui en cache date de plus de 30 secondes.

upload_url / uploadUrl / UploadURL génère une URL expirante (valable 1 heure par défaut) qui accepte un envoi direct, et renvoie url, method, headers et expires_in / expiresIn (en Go, un *filestore.UploadTarget avec URL, Method, Headers et ExpiresIn). Envoyez les en-têtes tels qu’ils sont renvoyés, afin que l’objet soit stocké avec le type de contenu fixé lors de la génération. Les types de contenu et la taille maximale de l’espace de noms, une size déclarée et le quota sont vérifiés au moment où l’URL est générée, et non lorsqu’elle est utilisée : l’URL n’est signée que pour l’hôte, de sorte que quiconque la détient peut écrire n’importe quel contenu sous sa clé jusqu’à son expiration. Comme share_url / shareUrl, c’est une capacité au porteur — une capacité d’écriture.

Objets volumineux

Le SDK choisit le transport en fonction de la taille, automatiquement — il n’y a rien à configurer :

La limite exacte est indiquée à l’exécution par le serveur sous la forme inline_max_bytes / inlineMaxBytes / InlineMaxBytes dans catalog() ; elle peut donc être relevée sans nouvelle version du SDK.

Le chemin direct exige un déploiement capable de pré-signer des URL et un appareil capable de joindre l’hôte du stockage d’objets, et pas seulement le routeur. Lorsque l’un des deux manque — le catalogue indique que le déploiement ne peut pas pré-signer (une appliance sur site, par défaut), la génération de l’URL de lecture répond NOT_SUPPORTED, ou le stockage d’objets est injoignable avant l’arrivée du moindre octet —, get (et get_to_file en Python, GetTo et GetToFile en Go) lisent l’objet par plages d’octets via le routeur à la place (FleetFiles v0.1.33 et ultérieur), chacune d’au plus la limite inline. Chaque plage est une lecture à part entière : un objet remplacé pendant une telle lecture la fait échouer avec INTERNAL (“object changed while it was read”). Les écritures n’ont pas de tel repli.

Deux plafonds subsistent pour les écritures, et tous deux signalent TOO_LARGE avec une raison précisant lequel a été atteint :

• 5 Gio — la limite d’envoi en une seule fois du stockage d’objets. L’envoi multipart n’est pas encore implémenté.
• La limite inline, lorsqu’il n’existe pas de point de terminaison direct — un déploiement qui ne peut pas pré-signer (une appliance, par défaut) ne peut tout simplement pas stocker un objet plus volumineux. Aucun nouvel essai ni découpage plus fin n’y changera quoi que ce soit, et le message le précise.

Deux défaillances du chemin direct courantes sur le terrain reçoivent leurs propres codes au lieu de ressembler à des problèmes d’autorisation : PRESIGN_UNREACHABLE (un proxy qui n’autorise que le routeur — une lecture se rabat sur les plages d’octets, une écriture échoue) et CLOCK_SKEW (le stockage d’objets rejette les requêtes décalées de plus de 15 minutes — vérifiez NTP sur l’appareil).

Erreurs de stockage de fichiers

Une défaillance du service de fichiers ou d’un transfert direct lève (Python) / lance (JavaScript) / renvoie (Go) une FileStoreError portant un code stable et une reason lisible par un humain. Faites vos branchements sur code, jamais sur reason. Les erreurs de fichiers locaux, un appel annulé et les erreurs WAMP du routeur autres que celles associées ci-dessous sont levées telles quelles.

from ironflock.filestore import FileStoreError
 
try:
    await ironflock.files.put("huge.bin", payload)
except FileStoreError as e:
    if e.code == "QUOTA_EXCEEDED":
        print("Filestore is full:", e.reason)
    else:
        raise

import { FileStoreError } from "ironflock";
 
try {
    await ironflock.files.put("huge.bin", payload);
} catch (e) {
    if (e instanceof FileStoreError && e.code === "QUOTA_EXCEEDED") {
        console.error("Filestore is full:", e.reason);
    } else {
        throw e;
    }
}

_, err := ifl.Files().Put(ctx, "huge.bin", payload)
var ferr *filestore.Error
if errors.As(err, &ferr) && ferr.Code == filestore.CodeQuotaExceeded {
	log.Println("Filestore is full:", ferr.Reason)
} else if err != nil {
	return err
}

Un serveur plus récent peut introduire des codes que cette version du SDK ne connaît pas. Ils sont transmis tels quels dans code plutôt que ramenés à une valeur générique : traitez donc une valeur non reconnue comme un échec générique.

Les appels de fichiers attendent la connexion jusqu’à 10 secondes (s’ils sont émis avant start() / Start, ils attendent aussi celui-ci) et ne sont pas retentés : contrairement aux opérations sur les tables, ils ne survivent pas à un redémarrage de la plateforme, si bien qu’un appel peut alors échouer avec NOT_AVAILABLE jusqu’à ce que le service de fichiers se soit de nouveau enregistré. Un tel appel n’a été exécuté nulle part ; votre app peut donc le répéter.

Clés. Le service de fichiers fait autorité sur les clés ; les SDK envoient les clés et les préfixes tels quels. Une clé ou un préfixe mal formé — vide ; avec un / initial ou final (hormis le préfixe de dossier d’iter / iterate) ; avec un segment vide, . ou .., ou un segment se terminant par . ou commençant ou se terminant par une espace ; avec l’un des caractères \ : * ? " < > | ^ ~, un caractère de contrôle ou un caractère de format Unicode ; de plus de 900 octets, 20 segments ou 255 octets par segment ; ou sous le préfixe réservé _sys/ — est refusé avec INVALID_KEY par un service de fichiers qui classe les erreurs de clé, et avec INTERNAL par FleetFiles v0.2. Attention aux horodatages : 2026-10-09T12:00:00Z n’est pas un segment de clé valide, à cause du :.

En Python, FileStoreError est importée depuis ironflock.filestore ; en JavaScript, elle est exportée depuis la racine du paquet (import { FileStoreError } from "ironflock") ; en Go, c’est *filestore.Error (aussi ironflock.FileStoreError), avec les codes sous forme de constantes comme filestore.CodeQuotaExceeded.

Communication inter-appareils

registerDeviceFunction / register_device_function

Enregistre une procédure que d’autres appareils exécutant la même app (dans le même stage) peuvent appeler, tout comme les actions des widgets de tableau de bord. Le SDK construit pour vous l’URI complète <SWARM_KEY>.<DEVICE_KEY>.<APP_KEY>.<STAGE>.<topic>, où STAGE vaut PROD lorsque ENV vaut PROD (quelle que soit la casse), et DEV sinon. Avant tout envoi, le SDK refuse un topic vide ainsi qu’une clé d’appareil, de projet ou d’app absente ou égale à 0 ; callDeviceFunction / call_device_function fait de même. Le routeur n’accepte aucun autre enregistrement de la part d’une app, et uniquement des enregistrements simples (voir URI autorisées pour une app). Sans connexion, la méthode attend une connexion au plus pendant la fenêtre de reconnexion (60 secondes par défaut, voir Fiabilité de la connexion). L’enregistrement est restauré après chaque reconnexion. La méthode renvoie un Registration, le handle de l’enregistrement : son unregister() le retire (voir unsubscribe / unregister).

def add(a, b):
    return a + b
 
await ironflock.register_device_function("com.myapp.add", add)

function add(args) {
    return args[0] + args[1];
}
 
await ironflock.registerDeviceFunction("com.myapp.add", add);

_, err := ifl.RegisterDeviceFunction(ctx, "com.myapp.add", func(ctx context.Context, inv *ironflock.Invocation) (any, error) {
	if len(inv.Args) != 2 {
		return nil, errors.New("add takes two numbers")
	}
	a, ok1 := inv.Args[0].(int64)
	b, ok2 := inv.Args[1].(int64)
	if !ok1 || !ok2 {
		return nil, fmt.Errorf("add takes two integers, got %T and %T", inv.Args[0], inv.Args[1])
	}
	return a + b, nil
})
if err != nil {
	return err
}

Les anciens noms register_function / registerFunction / RegisterFunction et call_function / callFunction / CallFunction fonctionnent toujours, mais sont obsolètes.

Apps qui redéfinissent ENV : les versions du SDK jusqu’à 1.8.6 (Python) et 1.8.4 (JavaScript) placent la valeur brute de ENV dans le segment du stage. Cela n’a d’incidence que lorsqu’une app définit elle-même ENV avec une autre graphie, comme prod : les appareils équipés de ces versions et ceux équipés de versions plus récentes ne peuvent alors pas appeler mutuellement leurs fonctions.

callDeviceFunction / call_device_function

Appelle une procédure enregistrée par un autre appareil de la même app. Le SDK assemble automatiquement le topic WAMP complet en utilisant la clé de l’appareil cible : <SWARM_KEY>.<device_key>.<APP_KEY>.<STAGE>.<topic>, la même URI que celle que registerDeviceFunction / register_device_function enregistre sur l’appareil cible.

result = await ironflock.call_device_function(
    42,                        # target device key
    "com.myapp.add",           # procedure name
    args=[3, 5]                # arguments
)
print(result)  # 8

const result = await ironflock.callDeviceFunction(
    42,                        // target device key
    "com.myapp.add",           // procedure name
    [3, 5]                     // arguments
);
console.log(result);  // 8

res, err := ifl.CallDeviceFunction(ctx,
	42,              // target device key
	"com.myapp.add", // procedure name
	3, 5,            // arguments
)
if err != nil {
	return err
}
log.Println(res.Value()) // 8

call

Appelle une procédure distante en utilisant une URI WAMP complète. Une app ne peut pas enregistrer un nom comme some.full.wamp.topic ; un tel nom n’atteint donc que les procédures que les services de la plateforme enregistrent sur le realm de données de l’app, comme celles du backend de données et du stockage de fichiers. Pour appeler une fonction qu’un autre appareil de votre app a enregistrée, utilisez callDeviceFunction / call_device_function.

result = await ironflock.call("some.full.wamp.topic", args=[42])

const result = await ironflock.call("some.full.wamp.topic", [42]);

result, err := ifl.Call(ctx, "some.full.wamp.topic", 42)
if err != nil {
	return err
}
log.Println(result.Value())

URI autorisées pour une app

Le conteneur de votre app rejoint son propre realm de données, realm-<SWARM_KEY>-<APP_KEY>-<dev|prod>, avec le rôle de routeur app. Le routeur y vérifie chaque publication, abonnement, appel et enregistrement par rapport à la liste d’autorisations de ce rôle. Les méthodes propres au SDK restent dans ce cadre ; les règles comptent lorsque vous passez vos propres URI à publish, subscribe ou call, ou que vous utilisez directement la connection (Connection() en Go). Une action refusée échoue avec wamp.error.not_authorized. En Python, la méthode lève une RuntimeError, et wamp_error_uri(err) renvoie l’URI ; en JavaScript, l’erreur est une WampError dont error est l’URI ; en Go, ironflock.WampURI(err) la renvoie.

Noms soumis au contrôle d’identité. Les noms qui commencent par un chiffre — les topics d’écriture des tables et les URI des fonctions d’appareil — passent en outre le contrôle d’identité de la plateforme, qui les lie à la clé de swarm de votre realm. Un enregistrement n’est accepté que pour une URI de fonction de votre propre appareil avec la clé de swarm, la clé d’app et le stage de votre realm ; un enregistrement par préfixe ou par wildcard, uniquement s’il fixe ces quatre segments. La publication et l’appel n’exigent que la clé de swarm de votre realm : une ligne publiée sur un topic de table avec une autre clé d’app est acceptée, mais n’atteint aucun backend de données et est perdue. Laissez le SDK construire ces URI.

Noms réservés. Le routeur refuse sys., hormis les deux procédures inter-apps ci-dessus, et wamp., hormis wamp.session.get. Les autres noms du tableau appartiennent à la plateforme : ne commencez pas vos propres noms par un chiffre, bulk., transformed., databackend.errors., files., append., appendBulk., history. ou secret.. Tout autre premier segment constitue l’espace de topics propre à votre app.

Personne ne s’abonne aux topics bruts des tables. Ils transportent la ligne exactement telle qu’elle a été envoyée, y compris le texte en clair des colonnes secrètes, que le backend de données ne chiffre qu’au moment où il stocke la ligne. subscribeToTable / subscribe_to_table lit plutôt les lignes stockées depuis transformed.<table>, typées et avec les colonnes secrètes masquées.

Les données des autres apps sont en lecture seule. Sur le realm d’un fournisseur, votre app (rôle de routeur app_reader) peut uniquement s’abonner à transformed.… et files.events… et appeler history.transformed.… et files.read.…, en plus du heartbeat wamp.session.get — pas de publication, pas d’enregistrement, pas d’écritures et pas de procédures de secrets.

Métadonnées de l’appareil

setDeviceLocation / set_device_location

Demande à la plateforme de mettre à jour la localisation GPS de l’appareil, que les cartes IronFlock affichent en temps réel.

Indisponible pour le moment : aucun service de la plateforme ne répond encore à cet appel sur le realm de données de l’app ; il échoue donc avec wamp.error.no_such_procedure. Conservez les localisations dans une table qui vous est propre en attendant.

await ironflock.set_device_location(long=8.6821, lat=50.1109)

await ironflock.setDeviceLocation(8.6821, 50.1109);

_, err := ifl.SetDeviceLocation(ctx, 8.6821, 50.1109) // long, lat
if err != nil {
	return err // wamp.error.no_such_procedure for now
}

L’historique de localisation n’est pas stocké. Pour suivre la localisation dans le temps, créez une table dédiée et utilisez publish_to_table / publishToTable.

getRemoteAccessUrlForPort

Renvoie l’URL sous laquelle un port déclaré dans le port-template.yml de l’app est joignable une fois son tunnel actif.

url = ironflock.getRemoteAccessUrlForPort(8080)
# "https://<device_key>-<app_name>-8080.app.ironflock.com"
 
vnc = ironflock.getRemoteAccessUrlForPort(5900, protocol="tcp")
# "tcp://app.ironflock.com:<the tunnel's remote port>"

const url = ironflock.getRemoteAccessUrlForPort(8080);
// "https://<device_key>-<app_name>-8080.app.ironflock.com"
 
const vnc = ironflock.getRemoteAccessUrlForPort(5900, "tcp");
// "tcp://app.ironflock.com:<the tunnel's remote port>"

url, ok := ifl.GetRemoteAccessURLForPort(8080, "", "")
// "https://<device_key>-<app_name>-8080.app.ironflock.com", true
 
vnc, ok := ifl.GetRemoteAccessURLForPort(5900, "tcp", "")
// "tcp://app.ironflock.com:<the tunnel's remote port>", true

Les ports http et https sont servis sous le label de tunnel <device_key>-<app name, lower case>-<port> (les ports https avec le préfixe secure- de la plateforme) sur le domaine de tunnel que l’agent de l’appareil injecte (TUNNEL_DOMAIN), toujours sous forme d’URL https://. Sur un appareil qui appartient à une appliance sur site (l’agent injecte INSTANCE_KEY), c’est la route relayée par le cloud https://i<INSTANCE_KEY>-<label>.<CLOUD_TUNNEL_DOMAIN> qui est renvoyée.

Une URL tcp ou udp contient le port public attribué par le tunnel, que l’agent de l’appareil annonce sous REMOTE_PORT_FOR_<port> (agent 0.19.8 et ultérieur) : <protocol>://<TUNNEL_DOMAIN>:<remote port>. Sur l’appareil d’une appliance, le port exposé sur Internet, REMOTE_PORT_FOR_<port>_CLOUD, est préféré tant que l’agent l’annonce ; avant qu’il n’apparaisse, puis de nouveau une fois que l’agent l’a supprimé (relais cloud désactivé), c’est l’URL locale à l’appliance qui est renvoyée. Un port 0 n’a pas encore été attribué.

Les valeurs des ports sont lues en direct depuis /data/env ; rappelez donc la méthode plutôt que de mettre le résultat en cache. Certains cas ne peuvent pas être servis par l’URL :

• L’agent de l’appareil ne crée des tunnels que pour les ports des installations de production (PROD). Dans un conteneur de développement (DEV), l’URL http(s) est celle de l’installation PROD de la même app sur cet appareil, et tcp/udp n’en donnent aucune ; joignez plutôt une app DEV via l’adresse LAN de l’appareil (DEVICE_LAN_IP, DEVICE_PORT_FOR_<port>).
• Sur un appareil edge d’une appliance installée sans domaine (mode HTTP en clair), l’agent définit TUNNEL_DOMAIN sur localhost, de sorte que les URL composées sur cet appareil pointent vers localhost : une telle appliance sert les ports des apps sur ses ports hôtes, ce qu’une URL de tunnel ne peut pas exprimer.
• Les domaines de tunnel non définis ou vides valent par défaut app.ironflock.com. La plateforme ne définit pas CLOUD_TUNNEL_DOMAIN aujourd’hui : les URL d’une appliance utilisent app.ironflock.com, sauf si l’app définit elle-même cette variable dans ses paramètres d’environnement.
• Dans un conteneur qui s’exécute sous un utilisateur autre que root, les valeurs sont celles avec lesquelles le conteneur a démarré (voir Variables d’environnement).

La méthode renvoie None / null (en Go "" et false) lorsque l’URL ne peut pas être composée : la clé de l’appareil ou le nom de l’app est manquant, aucun port distant n’a encore été annoncé pour un port tcp/udp (ou il vaut 0), le protocole est inconnu, ou le label n’est pas un label DNS valide (plus de 63 caractères, ou un nom d’app contenant un point). Dans un navigateur, il n’y a pas d’environnement : l’URL http(s) est composée sur app.ironflock.com à partir des options deviceKey et appName.

Propriétés & cycle de vie de la connexion

Fiabilité de la connexion

Le SDK se reconnecte tout seul. Lorsque la connexion tombe, il réessaie jusqu’au retour du routeur, puis restaure chaque abonnement et chaque fonction d’appareil enregistrée — vous n’avez pas à vous réabonner après une reconnexion, et les handles obtenus restent valides : leur active indique si chacun est actuellement actif auprès du routeur (voir unsubscribe / unregister). Les abonnements aux tables transmettent en outre les lignes stockées pendant la coupure de la connexion (voir subscribeToTable) ; les messages de vos propres topics ne sont en revanche pas stockés : ce qui a été publié entre-temps est perdu. Si l’un d’eux ne peut pas être restauré, les autres le sont quand même, et celui qui a échoué est retenté tant que la session dure — après 1 seconde, en doublant jusqu’à 30 secondes, chaque attente variant de 15 % au plus — puis de nouveau après chaque reconnexion : le routeur l’avait accepté auparavant, son refus est donc passager, comme lorsque le contrôle d’identité d’une fonction d’appareil par la plateforme échoue brièvement en mode fermé. Le premier échec est journalisé comme avertissement, et la restauration est journalisée dès qu’elle réussit.

Les opérations sur les tables — écritures dans les tables, lectures d’historique, de séries et de secrets, ainsi que les lectures d’historique et de séries d’une app consommée — survivent aussi à un redémarrage de la plateforme, comme une mise à jour du routeur ou de la plateforme. Elles attendent jusqu’à reconnect_window (Python, en secondes) / reconnectWindowMs (JavaScript) / WithReconnectWindow (Go, un time.Duration), 60 secondes par défaut, le retour de la connexion ; une opération émise avant start() / Start attend celui-ci dans la limite de la même fenêtre. Elles réessaient aussi tant que le backend de données ne sert pas encore ses procédures : le routeur répond wamp.error.no_such_procedure, ou le backend de données refuse un appel arrivé avant son enregistrement avec “client has no handler for registration”. Un tel appel n’a jamais atteint de gestionnaire, de sorte qu’une nouvelle tentative n’écrit jamais une ligne deux fois ; toute autre erreur est levée telle quelle. La lecture de rattrapage d’un abonnement de table fait partie de ces lectures.

Les écritures dans les tables comprennent publishToTable / publish_to_table, publishRowsToTable / publish_rows_to_table et reportError / report_error : elles appellent les mêmes procédures d’ajout que appendToTable et appendRowsToTable, si bien qu’une ligne écrite pendant que le backend de données redémarre n’est pas perdue.

publish, subscribe, subscribeToTable / subscribe_to_table (y compris celui d’une app consommée) et registerDeviceFunction / register_device_function attendent eux aussi une connexion dans les limites de la fenêtre de reconnexion, si bien qu’une courte coupure ne les fait pas échouer. Ils ne sont pas retentés ; un abonnement ou un enregistrement est restauré après chaque reconnexion ultérieure.

Toutes les autres opérations — call, callDeviceFunction / call_device_function, setDeviceLocation / set_device_location, les appels de fichiers, ainsi que la découverte inter-apps et l’ouverture des connexions aux apps consommées — attendent une connexion jusqu’à 10 secondes et ne sont pas retentées. Une opération émise avant start() / Start attend celui-ci dans la limite de ces 10 secondes. Une opération qui n’obtient pas de connexion pendant son attente échoue avec une erreur qui indique la durée de l’attente en secondes : en Python, les méthodes d’IronFlock lèvent une RuntimeError dont la cause est une TimeoutError ; en JavaScript, c’est une Error ordinaire ; en Go, une erreur qui enveloppe wamp.ErrNotConnected. unsubscribe et unregister n’attendent pas du tout : ils prennent effet immédiatement, même pendant que la connexion est coupée (voir unsubscribe / unregister).

0 désactive la fenêtre : ces opérations se comportent alors comme toutes les autres opérations. Elles attendent une connexion pendant 10 secondes et ne sont pas retentées, si bien qu’un rattrapage juste après un redémarrage de la plateforme n’est pas retenté non plus. Une fenêtre négative, et en Python et en JavaScript aussi NaN ou une valeur infinie, est refusée à la création de l’objet IronFlock (voir Options du constructeur).

Une requête déjà envoyée lorsque sa session se ferme (le routeur la ferme, le lien tombe ou stop()) échoue immédiatement au lieu d’attendre une réponse, et n’est pas retentée : elle a peut-être atteint son gestionnaire. En Python, la cause de l’erreur est l’ApplicationError d’autobahn portant la raison de la fermeture (par ex. wamp.close.system_shutdown), ou TransportLost lorsque le lien est tombé. En JavaScript, c’est une WampError dont error est la raison de la fermeture : celle du routeur, wamp.close.goodbye_and_out après stop(), ou wamp.close.transport_lost lorsque le lien est tombé. En Go, une telle requête échoue avec une erreur qui enveloppe wamp.ErrNotConnected (wamp.ErrStopped après Stop).

Un cas particulier est un routeur joignable qui n’a pas encore de realm pour l’app. Lors d’une installation concurrente, le conteneur de l’app démarre avant que le backend de données ait provisionné son realm, si bien que les premières tentatives de connexion sont refusées avec wamp.error.no_such_realm ; le SDK réessaie toutes les quelques secondes et l’app démarre dès que le realm existe. Un realm toujours absent après une minute n’apparaîtra très probablement jamais — l’app a été supprimée ou n’a pas de backend de données pour ce stage —, le SDK ralentit donc à partir de là à une tentative toutes les deux minutes au lieu de solliciter le routeur chaque seconde indéfiniment. La cadence rapide revient dès que le realm apparaît, ou dès que le routeur lui-même disparaît puis revient.

stop() / Stop met fin immédiatement à toute attente. Une opération qui attend encore une connexion — ou, si elle a été émise avant start() / Start, qui attend celui-ci — échoue avec l’erreur d’arrêt du SDK, de même qu’une opération sur une table en pause entre deux tentatives : en Python, une ConnectionError indiquant que la connexion IronFlock a été arrêtée (les méthodes d’IronFlock la lèvent comme cause de leur RuntimeError), en JavaScript une ConnectionStoppedError, et en Go une erreur qui enveloppe wamp.ErrStopped. Un start() qui attend encore de rejoindre son realm pour la première fois — un realm qui n’existe pas encore, par exemple — échoue avec Connection to realm <realm> stopped before it opened ; en Go, Start renvoie une erreur qui enveloppe wamp.ErrStopped. Un connect_to_app / connectToApp qui ouvre encore la connexion à un fournisseur échoue avec Connection to app '<app>' (<stage>) aborted by stop() ou, si la connexion rejoint quand même le realm, celle-ci est fermée et l’appel échoue avec Connection to app '<app>' (<stage>) closed by stop(). En Go, ConnectToApp échoue avec ironflock: connection to app '<app>' (<stage>) aborted by Stop (ou closed by Stop). Un refus qui survient en même temps que stop() conserve son CrossAppAccessError. En Python et en JavaScript, plus rien n’est en cours de connexion lorsque stop() rend la main, et un routeur qui ne répond pas quand la connexion quitte le realm est déconnecté après 5 secondes ; le Stop de Go attend la sortie du realm dans les limites de ctx, puis ferme le socket, et Run lui accorde 10 secondes.

En Python et en JavaScript, l’instance peut être redémarrée après stop() : start() se connecte à nouveau, et une opération émise après stop() attend le start() suivant, comme le fait une opération émise avant le premier start(). Le Stop de Go est définitif : une opération émise après lui échoue immédiatement avec wamp.ErrStopped.

Le cas le plus délicat est une connexion qui meurt silencieusement : un NAT ou un proxy la coupe après une période d’inactivité sans prévenir ni l’une ni l’autre extrémité, ou un routeur redémarre derrière un répartiteur de charge. Rien n’arrive pour signaler la perte. Une application qui ne fait que publier s’en aperçoit à sa prochaine écriture en échec, mais une application qui ne fait que s’abonner n’écrit jamais : sans aide, elle reste morte jusqu’au redémarrage du conteneur.

Les trois SDK détectent cette situation. La détection est active par défaut et ne demande aucune configuration.

const ironflock = new IronFlock();
 
ironflock.connection.heartbeatIntervalMs = 60000; // probe every 60s
ironflock.connection.heartbeatTimeoutMs = 15000;  // allow 15s to answer
 
await ironflock.start();

Les connexions inter-applications ouvertes avec connectToApp / connect_to_app ne font généralement que s’abonner, ce qui est précisément le cas que cela protège. Elles sont couvertes automatiquement, et elles se reconnectent aussi après un refus du routeur, jusqu’à ce que le refus persiste (voir connectToApp).