Fleet connection map#

PropertyValue
Servicecrossfire
OperationfleetMap
MethodGET
Path/api/fleets/{fleetId}/map
Authenticationhuman
Success status200
Response dataUnpaginated value
Request formatjson
Maximum request body2097152 bytes (service default)
Permission codesagent.read.owned, agent.read.any

Listed permission codes are alternatives, not token scopes. The service also checks access to the requested records and rejects stale revisions or controller generations.

Path parameters#

object; fields below; unknown fields rejected

Field pathRepresentation and constraints
fleetIdlowercase opaque UUID

Validation#

check.object({ fleetId: check.identifier })

Referenced definitions:

Query parameters#

custom validation: none ; see function below

Query parameters are URL text. The validation function below specifies their format, defaults and combinations. Pagination applies only to operations that use it.

Additional checks#

The following checks apply in addition to the field limits.

Constraint on value:

export function none(input: unknown) {
    const parsed = listQuery([])(input);
    return parsed.ok ? success({}) : parsed;
}

Validation#

query.none

Referenced definitions:

Request body#

empty object; unknown fields rejected

Validation#

check.empty

Referenced definitions:

Response data#

object; fields below; unknown fields rejected; constraint: Fleet map contains duplicate or disconnected identities ( fleetMap )

Field pathRepresentation and constraints
fleetobject; fields below; unknown fields rejected ( fleet )
fleet.fleetIdlowercase opaque UUID
fleet.ownerobject; fields below; unknown fields rejected ( principal )
fleet.owner.principalIdlowercase opaque UUID
fleet.owner.matrixUserIdwell-formed Matrix user ID; maximum 255 UTF-16 units
fleet.owner.kindhuman or agent
fleet.owner.displayNamestring; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls
fleet.owner.ownerIdlowercase opaque UUID
fleet.owner.ownerMatrixIdwell-formed Matrix user ID; maximum 255 UTF-16 units
fleet.fleetKeylowercase name; pattern [a-z][a-z0-9-]{0,39}
fleet.labelstring; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls
fleet.controllerobject; fields below; unknown fields rejected ( controller )
fleet.controller.namestring; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls
fleet.controller.metadatacustom validation: metadata ; see function below; optional property
fleet.revisionexact JSON integer; 0…9007199254740991
fleet.createdAtexact JSON integer; 0…9007199254740991
fleet.updatedAtexact JSON integer; 0…9007199254740991
fleet.deliveryobject; fields below; unknown fields rejected ( fleetControl )
fleet.delivery.fleetIdlowercase opaque UUID
fleet.delivery.revisionexact JSON integer; 0…9007199254740991
fleet.delivery.deliveryEnabledboolean
fleet.delivery.connectionobject; fields below; unknown fields rejected
fleet.delivery.connection.statusonline or offline
fleet.delivery.connection.lastSeenAtexact JSON integer; 0…9007199254740991; JSON null permitted
fleet.canArchiveboolean
fleet.allowedActionsarray; 0–2 entries; item: configure or archive
capturedAtexact JSON integer; 0…9007199254740991
agentsarray; 0–1000 entries; item: object; fields below; unknown fields rejected ( mapAgent )
agents[].agentIdlowercase opaque UUID
agents[].matrixUserIdwell-formed Matrix user ID; maximum 255 UTF-16 units
agents[].instanceKeylowercase name; pattern [a-z][a-z0-9-]{0,39}
agents[].displayNamestring; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls
agents[].statusvalidator choice('active', 'suspended', 'revoked') ( status )
agents[].ownerobject; fields below; unknown fields rejected ( owner )
agents[].owner.memberIdlowercase opaque UUID
agents[].owner.matrixUserIdwell-formed Matrix user ID; maximum 255 UTF-16 units
agents[].owner.displayNamestring; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls
agents[].owner.statusvalidator choice('active', 'suspended', 'revoked') ( status )
agents[].sourceIdstring; 64–64 UTF-16 units; well-formed Unicode; no C0/DEL controls
agents[].listeneronline or offline or disconnecting
agents[].lastSeenAtexact JSON integer; 0…9007199254740991; JSON null permitted
roomsarray; 0–2000 entries; item: object; fields below; unknown fields rejected ( mapRoom )
rooms[].roomIdimmutable Matrix room ID; maximum 255 UTF-16 units
rooms[].namestring; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls; JSON null permitted
rooms[].aliasstring; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls; JSON null permitted
connectionsarray; 0–10000 entries; item: object; fields below; unknown fields rejected ( mapConnection )
connections[].agentIdlowercase opaque UUID
connections[].roomIdimmutable Matrix room ID; maximum 255 UTF-16 units
connections[].grantobject; fields below; unknown fields rejected ( grant ); JSON null permitted
connections[].grant.agentIdlowercase opaque UUID
connections[].grant.roomIdimmutable Matrix room ID; maximum 255 UTF-16 units
connections[].grant.generationlowercase opaque UUID
connections[].grant.authorizerIdlowercase opaque UUID
connections[].grant.addedByIdlowercase opaque UUID
connections[].grant.accessModenone or read or reply or custom
connections[].grant.powerLevelexact JSON integer; -9007199254740991…9007199254740991; JSON null permitted
connections[].grant.mutedboolean
connections[].grant.revisionexact JSON integer; 0…9007199254740991
connections[].grant.accessRevisionexact JSON integer; 0…9007199254740991
connections[].grant.updatedAtexact JSON integer; 0…9007199254740991
connections[].applicationobject; fields below; unknown fields rejected; constraint: Native creators have no finite power level ( grantApplication ); JSON null permitted
connections[].application.observedGenerationlowercase opaque UUID; JSON null permitted
connections[].application.appliedRevisionexact JSON integer; 0…9007199254740991; JSON null permitted
connections[].application.appliedAccessRevisionexact JSON integer; 0…9007199254740991; JSON null permitted
connections[].application.membershipjoin or invite or leave or ban; JSON null permitted
connections[].application.creatorboolean
connections[].application.powerLevelexact JSON integer; -9007199254740991…9007199254740991; JSON null permitted
connections[].application.lastAttemptAtexact JSON integer; 0…9007199254740991; JSON null permitted
connections[].application.lastSuccessAtexact JSON integer; 0…9007199254740991; JSON null permitted
connections[].application.errorCodestring; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls; JSON null permitted
connections[].application.errorMessagestring; 1–4096 UTF-16 units; well-formed Unicode; no C0/DEL controls; JSON null permitted
sourcesarray; 0–1000 entries; item: object; fields below; unknown fields rejected ( mapSource )
sources[].sourceIdstring; 64–64 UTF-16 units; well-formed Unicode; no C0/DEL controls
sources[].modevalidator choice('selected', 'humans', 'everyone') ( wakeMode )
sources[].sendersarray; 0–2000 entries; item: object; fields below; unknown fields rejected ( wakeSelection )
sources[].senders[].principalIdlowercase opaque UUID
sources[].senders[].includeAgentsboolean
sources[].eligiblePrincipalIdsarray; 0–2000 entries; item: lowercase opaque UUID
principalsarray; 0–2000 entries; item: object; fields below; unknown fields rejected ( principal )
principals[].principalIdlowercase opaque UUID
principals[].matrixUserIdwell-formed Matrix user ID; maximum 255 UTF-16 units
principals[].kindhuman or agent
principals[].displayNamestring; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls
principals[].ownerIdlowercase opaque UUID
principals[].ownerMatrixIdwell-formed Matrix user ID; maximum 255 UTF-16 units

Additional checks#

The following checks apply in addition to the field limits.

Constraint on object:

value => {
    const agents = new Set(value.agents.map(agent => agent.agentId)), rooms = new Set(value.rooms.map(room => room.roomId));
    const sources = new Set(value.sources.map(source => source.sourceId)), principals = new Set(value.principals.map(identity => identity.principalId));
    return agents.size === value.agents.length && rooms.size === value.rooms.length && sources.size === value.sources.length && principals.size === value.principals.length
        && value.agents.every(agent => sources.has(agent.sourceId) && agent.owner.memberId === value.fleet.owner.principalId)
        && value.sources.every(source => [...source.senders.map(sender => sender.principalId), ...source.eligiblePrincipalIds].every(id => principals.has(id))
            && new Set(source.senders.map(sender => sender.principalId)).size === source.senders.length && new Set(source.eligiblePrincipalIds).size === source.eligiblePrincipalIds.length
            && source.senders.every(sender => !sender.includeAgents || value.principals.some(identity => identity.principalId === sender.principalId && identity.kind === 'human'))
            && (source.mode !== 'everyone' || source.senders.length === 0)
            && value.agents.some(agent => agent.sourceId === source.sourceId))
        && new Set(value.connections.map(connection => connection.agentId + '\0' + connection.roomId)).size === value.connections.length
        && value.connections.every(connection => agents.has(connection.agentId) && rooms.has(connection.roomId)
            && (connection.grant !== null || connection.application !== null)
            && (connection.grant === null || connection.grant.agentId === connection.agentId && connection.grant.roomId === connection.roomId))
        && value.rooms.every(room => value.connections.some(connection => connection.roomId === room.roomId));
}

Constraint on fleet.controller.metadata:

function metadata(input: unknown): Result<Record<string, string>> {
    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length > 16)
        return failure('invalid', 'Controller metadata supports at most 16 text fields');
    const output: Record<string, string> = {};
    for (const [key, value] of Object.entries(input)) {
        if (!/^[a-z][a-z0-9-]{0,39}$/u.test(key) || !check.text(256, 0)(value).ok || typeof value !== 'string')
            return failure('invalid', 'Invalid controller metadata');
        output[key] = value;
    }
    return success(output);
}

Constraint on connections[].application:

application => !application.creator || application.powerLevel === null

Validation#

fleetMap

Referenced definitions:

Response envelope#

A successful JSON response contains data and meta. Replace the data placeholder below with the response fields described above. Errors contain error instead of data.

{
  "data": "<value matching the response-data validator>",
  "meta": {
    "requestId": "00000000-0000-0000-0000-000000000001"
  }
}