/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { SupportedTransportsBitmap, SupportedTransportsSchema } from "#common/SupportedTransportsBitmap.js"; import { DEFAULT_MAX_TCP_MESSAGE_SIZE, ImplementationError, MAX_UDP_MESSAGE_SIZE, UINT16_MAX, UINT32_MAX, } from "@matter/general"; import { Specification } from "@matter/model"; import { SessionIntervals } from "./SessionIntervals.js"; /** * Minimum peer specification version for which TCP transport is honored. Some Matter 1.4 devices advertise TCP * support but do not implement it reliably, so {@link SessionParameters} clears TCP from the supported transports of * any peer reporting an older (or unknown) spec version. */ export const MIN_TCP_SPEC_VERSION = 0x01050000; export interface SessionParameters extends SessionIntervals { /** Version of Data Model for the Session parameters side where it appears. */ dataModelRevision: number; /** Version of Interaction Model for the Session parameters side where it appears. */ interactionModelRevision: number; /** Version of Specification for the Session parameters side where it appears. */ specificationVersion: number; /** The maximum number of elements in the InvokeRequests list that the Node is able to process. */ maxPathsPerInvoke: number; /** A bitmap of the supported transport protocols in addition to MRP. */ supportedTransports: SessionParameters.SupportedTransports; /** * Maximum size of the message carried over TCP, excluding the framing message length field, that the node is * capable of receiving from its peer. */ maxTcpMessageSize?: number; } export function SessionParameters(config?: SessionParameters.Config): SessionParameters { const { supportedTransports: reportedTransports, maxPathsPerInvoke, maxTcpMessageSize: reportedMaxTcpMessageSize, ...reported } = SessionParameters.reported(config) ?? {}; // TCP is only honored for Matter 1.5.0+ peers; clear it for older or unknown spec versions so supportedTransports // is the single source of truth for transport selection. let supportedTransports: SessionParameters.SupportedTransports = reportedTransports ?? SessionParameters.fallbacks.supportedTransports; const specificationVersion = reported.specificationVersion ?? SessionParameters.fallbacks.specificationVersion; if (specificationVersion < MIN_TCP_SPEC_VERSION) { supportedTransports = { tcpClient: false, tcpServer: false }; } // The MAX_TCP_MESSAGE_SIZE field SHALL only be present if the SUPPORTED_TRANSPORTS field indicates that TCP is // supported let maxTcpMessageSize: number | undefined; if (supportedTransports.tcpClient || supportedTransports.tcpServer) { maxTcpMessageSize = reportedMaxTcpMessageSize === undefined || reportedMaxTcpMessageSize === 0 ? SessionParameters.fallbacks.maxTcpMessageSize : reportedMaxTcpMessageSize; } // The MaxPathsPerInvoke attribute defines zero as "assume one", and the MAX_PATHS_PER_INVOKE session parameter // carries that same attribute as a uint16. Persisted parameters reach us untyped, so anything the wire could not // have carried takes the fallback. const validMaxPathsPerInvoke = typeof maxPathsPerInvoke === "number" && Number.isInteger(maxPathsPerInvoke) && maxPathsPerInvoke >= 1 && maxPathsPerInvoke <= UINT16_MAX; return { ...SessionParameters.fallbacks, ...reported, ...(validMaxPathsPerInvoke ? { maxPathsPerInvoke } : {}), supportedTransports, maxTcpMessageSize, }; } export namespace SessionParameters { export interface SupportedTransports extends Partial {} /** * Normalize the session parameters a peer sent without filling fallbacks: decode the supported transports and drop * values the peer left out. Undefined when nothing remains. */ export function reported(config?: Config): Partial | undefined { if (config === undefined) { return undefined; } const { supportedTransports, ...rest } = config; const result: Partial = {}; for (const [key, value] of Object.entries(rest)) { if (value !== undefined) { Object.assign(result, { [key]: value }); } } if (supportedTransports !== undefined) { result.supportedTransports = typeof supportedTransports === "number" ? SupportedTransportsSchema.decode(supportedTransports) : supportedTransports; } return Object.keys(result).length ? result : undefined; } /** * Validate a MAX_TCP_MESSAGE_SIZE we configure for ourselves: a whole number from {@link MAX_UDP_MESSAGE_SIZE} to * the uint32 maximum of the session parameter field. * * @param name names the setting in the error message * @throws ImplementationError for any other value */ export function assertMaxTcpMessageSize(maxTcpMessageSize: number, name = "Max TCP Message Size") { if ( !Number.isInteger(maxTcpMessageSize) || maxTcpMessageSize < MAX_UDP_MESSAGE_SIZE || maxTcpMessageSize > UINT32_MAX ) { throw new ImplementationError( `${name} of ${maxTcpMessageSize} is not a whole number from ${MAX_UDP_MESSAGE_SIZE} to ${UINT32_MAX}`, ); } } export interface Config extends Partial> { supportedTransports?: number | SupportedTransports; } /** * Session parameters we use for peers if not supplied by the peer. */ export const fallbacks = { ...SessionIntervals.defaults, /** * Fallback value for Data Model Revision when not provided in Session parameters. We use Matter 1.2 as * assumption. */ dataModelRevision: 17, /** * Fallback value for Interaction Model Revision when not provided in Session parameters. We use Matter 1.2 as * assumption. */ interactionModelRevision: 11, /** * Fallback value for Specification Version when not provided in Session parameters. We use 0 as assumption which is * "before 1.3". */ specificationVersion: 0, /** * Fallback value for the maximum number of paths that can be included in a single invoke message when not * provided in, or reported as zero by, Session parameters. * * @see {@link MatterSpecification.v161.Core} § 11.1.5.23 */ maxPathsPerInvoke: 1, /** * No TCP support by default. */ supportedTransports: {}, /** * Fallback value for MAX_TCP_MESSAGE_SIZE when a TCP-capable peer does not provide it, or reports zero. * Zero cannot be a real limit; a stack sends it when it announces TCP support without setting a size. * * @see {@link MatterSpecification.v161.Core} § 4.13.1 */ maxTcpMessageSize: DEFAULT_MAX_TCP_MESSAGE_SIZE, }; /** * Session parameters we use for ourselves. */ export const defaults = { ...fallbacks, dataModelRevision: Specification.DATA_MODEL_REVISION, interactionModelRevision: Specification.INTERACTION_MODEL_REVISION, specificationVersion: Specification.SPECIFICATION_VERSION, }; }