matter-js
diff --git a/‎.github/workflows/chip-tool-tests.yml‎
Lines changed: 38 additions & 0 deletions b/‎.github/workflows/chip-tool-tests.yml‎
Lines changed: 38 additions & 0 deletions
diff --git a/‎examples/controller/src/ControllerNode.ts‎
Lines changed: 2 additions & 1 deletion b/‎examples/controller/src/ControllerNode.ts‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎examples/device-onoff/src/DeviceNode.ts‎
Lines changed: 4 additions & 0 deletions b/‎examples/device-onoff/src/DeviceNode.ts‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎package-lock.json‎
Lines changed: 24 additions & 0 deletions b/‎package-lock.json‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎packages/general/src/net/Channel.ts‎
Lines changed: 49 additions & 5 deletions b/‎packages/general/src/net/Channel.ts‎
Lines changed: 49 additions & 5 deletions
diff --git a/‎packages/general/src/net/Network.ts‎
Lines changed: 13 additions & 2 deletions b/‎packages/general/src/net/Network.ts‎
Lines changed: 13 additions & 2 deletions
diff --git a/‎packages/general/src/net/ServerAddress.ts‎
Lines changed: 49 additions & 39 deletions b/‎packages/general/src/net/ServerAddress.ts‎
Lines changed: 49 additions & 39 deletions
@@ -254,6 +254,44 @@ jobs:
               --app-path lit-icd:../support/chip-testing/AllClustersTestApp.sh \
             '
 
+  # Execute core tests with TCP preferred to verify TCP transport
+  matterjs-tests-core-tcp:
+    needs: [prepare-chip-build, chip-tests-needed]
+    if: ${{ github.repository == 'matter-js/matter.js' && (needs.chip-tests-needed.outputs.chip-tool-rebuild == 'true' || needs.chip-tests-needed.outputs.chip-tests-required == 'true' || needs.chip-tests-needed.outputs.chip-changes == 'true') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out matter.js
+        uses: actions/checkout@v6
+
+      - name: Initialize chip tests
+        uses: ./.github/actions/prepare-chip-testing
+        with:
+          rebuild-chip-tool: "false"
+          patch-test-yaml: "true"
+
+      - name: Run Core cluster tests with TCP preferred
+        id: test-execution-08-core-matterjs-tcp
+        shell: bash
+        env:
+          TEST_PREFER_TCP: "1"
+        run: |
+          cd connectedhomeip
+          ./scripts/run_in_build_env.sh  \
+            'TEST_PREFER_TCP=1 ./scripts/tests/run_test_suite.py \
+              --runner chip_tool_python \
+              --log-level info \
+              --target-glob "{Test_TC_ACE_*,Test_TC_ACL_*,Test_TC_BINFO_*,Test_TC_CADMIN_*,Test_TC_CGEN_*,Test_TC_CNET_*,Test_TC_DESC_*,Test_TC_OPCREDS_*,TestAccessControlC*,TestArmFailSafe,TestCommandsById,TestCommissionerNodeId,TestCommissioningWindow,TestGeneralCommissioning,TestMultiAdmin,TestSubscribe_*}" \
+              run \
+              --iterations 1 \
+              --tool-path chip-tool:../support/chip-testing/dist/esm/ControllerWebSocketTestApp.js \
+              --app-path all-clusters:../support/chip-testing/dist/esm/AllClustersTestApp.js \
+              --app-path all-devices:../support/chip-testing/dist/esm/AllClustersTestApp.js \
+              --app-path bridge:../support/chip-testing/dist/esm/BridgeTestApp.js \
+              --app-path tv:../support/chip-testing/dist/esm/TvTestApp.js \
+              --app-path rvc:../support/chip-testing/AllClustersTestApp.sh \
+              --app-path lit-icd:../support/chip-testing/AllClustersTestApp.sh \
+            '
+
   # Execute the fast application cluster tests
   chip-tests-app-fast:
     needs: [prepare-chip-build, chip-tests-needed]
 
@@ -138,7 +138,8 @@ class ControllerNode {
             const options: NodeCommissioningOptions = {
                 commissioning: commissioningOptions,
                 discovery: {
-                    knownAddress: ip !== undefined && port !== undefined ? { ip, port, type: "udp" } : undefined,
+                    knownAddress:
+                        ip !== undefined && port !== undefined ? { ip, port, type: "udp" as const } : undefined,
                     identifierData:
                         longDiscriminator !== undefined
                             ? { longDiscriminator }
 
@@ -30,6 +30,7 @@ async function main() {
         productId,
         port,
         uniqueId,
+        tcp,
     } = await getConfiguration();
 
     /**
@@ -43,6 +44,7 @@ async function main() {
         // Optional when operating only one device on a host, Default port is 5540
         network: {
             port,
+            tcp,
         },
 
         // Provide Commissioning relevant settings
@@ -162,6 +164,7 @@ async function getConfiguration() {
     const productId = environment.vars.number("productid") ?? (await deviceStorage.get("productid", 0x8000));
 
     const port = environment.vars.number("port") ?? 5540;
+    const tcp = environment.vars.get("tcp") !== undefined ? true : undefined;
 
     const uniqueId =
         environment.vars.string("uniqueid") ?? (await deviceStorage.get("uniqueid", Time.nowMs)).toString();
@@ -189,5 +192,6 @@ async function getConfiguration() {
         productId,
         port,
         uniqueId,
+        tcp,
     };
 }
@@ -3,9 +3,11 @@
  * Copyright 2022-2026 Matter.js Authors
  * SPDX-License-Identifier: Apache-2.0
  */
-import { ServerAddressUdp } from "#net/ServerAddress.js";
-import { isObject } from "#util/Type.js";
+import { ServerAddressIp, ServerAddressUdp } from "#net/ServerAddress.js";
+import type { Transport } from "#net/Transport.js";
+import { Bytes } from "#util/Bytes.js";
 import { Observable } from "#util/index.js";
+import { isObject } from "#util/Type.js";
 
 export enum ChannelType {
     UDP = "udp",
@@ -35,28 +37,70 @@ export interface Channel<T> {
     close(): Promise<void>;
 }
 
-// TODO Enhance when we add TCP support
 export interface IpNetworkChannel<T> extends Channel<T> {
+    networkAddress: ServerAddressIp;
+    networkAddressChanged: Observable<[ServerAddressIp]>;
+
+    /** Send data to the remote endpoint */
+    send(data: T): Promise<void>;
+}
+
+/** UDP-specific channel with per-send address override capability. */
+export interface UdpNetworkChannel<T> extends IpNetworkChannel<T> {
     networkAddress: ServerAddressUdp;
     networkAddressChanged: Observable<[ServerAddressUdp]>;
 
     /** Send data, optionally overriding the destination address for this single send. */
     send(data: T, addressOverride?: ServerAddressUdp): Promise<void>;
 }
 
+/**
+ * Stream-oriented channel with a fixed peer (TCP, BLE/BTP).
+ *
+ * Both TCP and BLE channels are inherently reliable and have a connection lifecycle.
+ * Incoming messages are delivered as an async iterable; outgoing messages via send().
+ */
+export interface ConnectedChannel extends Channel<Bytes>, AsyncIterable<Bytes> {
+    readonly isReliable: true;
+    readonly supportsLargeMessages: boolean;
+    readonly type: ChannelType;
+
+    /** Send a complete Matter message to the peer. */
+    send(data: Bytes): Promise<void>;
+
+    /** Close the connection. */
+    close(): Promise<void>;
+
+    /** Register a listener for connection close/disconnect. */
+    onClose(listener: () => void): Transport.Listener;
+}
+
+/**
+ * Type guard for connected (stream-oriented) channels.
+ */
+export function isConnectedChannel(channel?: Channel<unknown>): channel is ConnectedChannel {
+    return channel !== undefined && channel.isReliable && typeof (channel as ConnectedChannel).onClose === "function";
+}
+
 /**
  * Returns true (and guards types) if the channel is an IP channel
  */
 export function isIpNetworkChannel<T>(channel?: Channel<T>): channel is IpNetworkChannel<T> {
     return isObject((channel as IpNetworkChannel<T> | undefined)?.networkAddress);
 }
 
+/**
+ * Returns true if the channel is a UDP network channel (supports address override).
+ */
+export function isUdpNetworkChannel<T>(channel?: Channel<T>): channel is UdpNetworkChannel<T> {
+    return isIpNetworkChannel(channel) && channel.type === ChannelType.UDP;
+}
+
 /**
  * Checks if two IPNetworkChannels are referencing the same address.
- * Both the channel type (UDP/TCP) and the address (including port) need to match.
  */
 export function sameIpNetworkChannel<T>(channel1: IpNetworkChannel<T>, channel2: IpNetworkChannel<T>) {
     const { networkAddress: addr1 } = channel1;
     const { networkAddress: addr2 } = channel2;
-    return addr1.type === addr2.type && addr1.ip === addr2.ip && addr1.port === addr2.port;
+    return addr1.ip === addr2.ip && addr1.port === addr2.port;
 }
@@ -6,7 +6,8 @@
 
 import { MatterError } from "../MatterError.js";
 import type { MaybePromise } from "../util/Promises.js";
-import type { UdpChannel, UdpChannelOptions } from "./udp/UdpChannel.js";
+import type { TcpConnection, TcpListener, TcpListenerOptions } from "./tcp/TcpConnection.js";
+import type { UdpSocket, UdpSocketOptions } from "./udp/UdpSocket.js";
 
 export class NetworkError extends MatterError {}
 
@@ -68,7 +69,17 @@ export type NetworkInterfaceDetailed = NetworkInterface & NetworkInterfaceDetail
 export abstract class Network {
     abstract getNetInterfaces(configuration?: NetworkInterface[]): MaybePromise<NetworkInterface[]>;
     abstract getIpMac(netInterface: string): MaybePromise<NetworkInterfaceDetails | undefined>;
-    abstract createUdpChannel(options: UdpChannelOptions): Promise<UdpChannel>;
+    abstract createUdpSocket(options: UdpSocketOptions): Promise<UdpSocket>;
+
+    /** Create a TCP server socket. Override in platform implementations that support TCP. */
+    createTcpListener(_options: TcpListenerOptions): Promise<TcpListener> {
+        throw new NetworkError("TCP server not supported on this platform");
+    }
+
+    /** Connect to a remote TCP endpoint. Override in platform implementations that support TCP. */
+    connectTcp(_host: string, _port: number, _options?: { timeout?: number }): Promise<TcpConnection> {
+        throw new NetworkError("TCP client not supported on this platform");
+    }
 
     async close() {
         // Nothing to do
 
@@ -42,24 +42,24 @@ export interface AddressStatus extends Partial<AddressLifespan> {
     weight?: number;
 }
 
-export type ServerAddressUdp = {
-    type: "udp";
+/** Transport-agnostic IP address as discovered via DNS-SD. */
+export type ServerAddressIp = {
     ip: string;
     port: number;
 } & AddressStatus;
 
-export type ServerAddressTcp = {
-    type: "tcp";
-    ip: string;
-    port: number;
-} & AddressStatus;
+/** IP address with explicit UDP transport. */
+export type ServerAddressUdp = ServerAddressIp & { type: "udp" };
+
+/** IP address with explicit TCP transport. */
+export type ServerAddressTcp = ServerAddressIp & { type: "tcp" };
 
 export type ServerAddressBle = {
     type: "ble";
     peripheralAddress: string;
 } & AddressStatus;
 
-export type ServerAddress = ServerAddressUdp | ServerAddressTcp | ServerAddressBle;
+export type ServerAddress = ServerAddressIp | ServerAddressUdp | ServerAddressTcp | ServerAddressBle;
 
 export function ServerAddress(definition: ServerAddress) {
     return {
@@ -70,41 +70,54 @@ export function ServerAddress(definition: ServerAddress) {
         priority: undefined,
         weight: undefined,
         ...definition,
-    } as ServerAddress;
+    } as unknown as ServerAddress;
 }
 
 export namespace ServerAddress {
-    export function urlFor(address: ServerAddress): string {
-        switch (address.type) {
-            case "udp":
-            case "tcp":
-                const ip = address.ip;
-                return `${address.type}://${ip.includes(":") ? `[${ip}]` : ip}:${address.port}`;
+    /** Type guard for IP-based addresses (with or without explicit transport type). */
+    export function isIp(address: ServerAddress): address is ServerAddressIp {
+        return (address as ServerAddressIp).ip !== undefined;
+    }
 
-            case "ble":
-                return `ble://${address.peripheralAddress}`;
+    /** Type guard for BLE addresses. */
+    export function isBle(address: ServerAddress): address is ServerAddressBle {
+        return (address as ServerAddressBle).peripheralAddress !== undefined;
+    }
 
-            default:
-                return `${(address as any).type}://`;
+    /** Returns the transport protocol label for display — "udp", "tcp", or "ip" if unspecified. */
+    export function protocolOf(address: ServerAddress): string {
+        if (isBle(address)) {
+            return "ble";
+        }
+        if ("type" in address && typeof address.type === "string") {
+            return address.type;
         }
+        return "ip";
     }
 
-    export function diagnosticFor(address: ServerAddress) {
-        const diagnostic = Array<unknown>();
+    export function urlFor(address: ServerAddress): string {
+        if (isIp(address)) {
+            const proto = protocolOf(address);
+            const host = address.ip.includes(":") ? `[${address.ip}]` : address.ip;
+            return `${proto}://${host}:${address.port}`;
+        }
 
-        switch (address.type) {
-            case "udp":
-            case "tcp":
-                diagnostic.push(`${address.type}://`, Diagnostic.strong(address.ip), ":", address.port);
-                break;
+        if (isBle(address)) {
+            return `ble://${address.peripheralAddress}`;
+        }
 
-            case "ble":
-                diagnostic.push("ble://", Diagnostic.strong(address.peripheralAddress));
-                break;
+        return `unknown://`;
+    }
 
-            default:
-                diagnostic.push(`${(address as any).type}://`);
-                break;
+    export function diagnosticFor(address: ServerAddress) {
+        const diagnostic = Array<unknown>();
+
+        if (isIp(address)) {
+            diagnostic.push(`${protocolOf(address)}://`, Diagnostic.strong(address.ip), ":", address.port);
+        } else if (isBle(address)) {
+            diagnostic.push("ble://", Diagnostic.strong(address.peripheralAddress));
+        } else {
+            diagnostic.push("unknown://");
         }
 
         if ("ttl" in address && typeof address.ttl === "number") {
@@ -114,16 +127,13 @@ export namespace ServerAddress {
         return Diagnostic.squash(...diagnostic);
     }
 
+    /** IP addresses are equal if ip and port match, regardless of transport type. */
     export function isEqual(a: ServerAddress, b: ServerAddress): boolean {
-        if (a.type !== b.type) {
-            return false;
-        }
-
-        if (a.type === "udp" && b.type === "udp") {
+        if (isIp(a) && isIp(b)) {
             return a.ip === b.ip && a.port === b.port;
         }
 
-        if (a.type === "ble" && b.type === "ble") {
+        if (isBle(a) && isBle(b)) {
             return a.peripheralAddress === b.peripheralAddress;
         }
 
@@ -170,7 +180,7 @@ export namespace ServerAddress {
     }
 
     export function selectionPreferenceOf(address: ServerAddress) {
-        if (!("ip" in address)) {
+        if (!isIp(address)) {
             return SelectionPreference.NOT_IP;
         }