Verify Server Endpoint Context

Verify server message endpoint context, endpoint type narrowing, plugin forwarding order, command observable emission, and Matter 1.6.0 comments on validation and state updates

Verify endpoint context in Matterbridge behavior server implementations.

Scope:

• Inspect all server implementations in packages/core/src/behaviors.
• Inspect all server classes declared in files under packages/core/src/devices, including files that also contain device classes or helper code.
• In device files, limit the check to server class bodies. Do not report logs or throws belonging only to device classes or unrelated helpers.

Checks:

• Verify every textual log and throw message in scope starts with the exact name of its enclosing server class, optionally followed by a dot and the exact name of the enclosing command handler or method, then a colon and one space, and that the first letter of the text immediately following that prefix is lowercase. For example:

  MatterbridgeBooleanStateConfigurationServer: requested;

  The optional method segment is intended for clusters whose handlers emit similar messages about the same subject, where the bare class name alone does not identify which command produced the line. For example:

  MatterbridgeWebRtcTransportProviderServer.provideOffer: received;

• Verify every textual log and throw message in scope ends with this exact fragment:

  (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber})

• Treat calls to every log level as logs, including debug, info, notice, warn, error, and fatal, whether the logger is accessed through device.log, this.state.log, this.log, or another local reference.

• Verify every error message created by a throw statement in scope follows the same prefix and suffix rules, including errors constructed directly in the throw and errors assigned to a variable before being thrown.

• Follow local variables and simple helper methods when needed so multiline calls, template literals, and indirectly constructed error messages are not missed.

• Do not accept a missing or abbreviated server name, text before the server name, a prefix that does not match the enclosing server class name exactly, a method segment that does not match the enclosing method name exactly, a method segment not separated from the server name by a single dot, a prefix whose colon and space separator is missing so the prefix runs into the message text, or an uppercase first letter immediately after the prefix's colon and space (for example MatterbridgeEnergyEvseServer: Disable charging is a violation; MatterbridgeEnergyEvseServer: disable charging is compliant, and MatterbridgeWebRtcTransportProviderServer.solicitOffer requires at least one stream is a violation because it has no colon and space separator; MatterbridgeWebRtcTransportProviderServer.solicitOffer: requires at least one stream is compliant).

• Do not accept alternate endpoint formats, missing parentheses, a colon separator, endpoint.id, endpoint.number, messages containing only one endpoint component, or any text after the endpoint fragment's closing parenthesis.

• Accept (endpoint ${endpointLabel}) only in a log written from a deferred callback (a timer, an un-awaited promise or similar) that can run after the command's behavior context has exited, where endpointLabel is a local const endpointLabel = \${this.endpoint.maybeId}.${this.endpoint.maybeNumber}`` captured synchronously before the deferral, with a comment explaining why. Report a label used in a synchronous log, a label built any other way, or a captured label without that comment as a violation.

• Do not require the fragment in a log or thrown value that has no textual message, but report that case separately for manual review.

• Ignore comments, JSDoc examples, tests, generated output, and imported server implementations.

Endpoint type narrowing:

• Verify every server class in scope narrows the inherited endpoint getter once, as the first member of the class body, instead of asserting the type at each use:

  /** The endpoint that owns this behavior. Narrowed to MatterbridgeEndpoint: this server is only ever added to a Matterbridge endpoint. */
  declare readonly endpoint: MatterbridgeEndpoint;

• Behavior.endpoint is a getter returning Endpoint<EndpointType.Empty> and MatterbridgeEndpoint is a subtype of it, so the narrowing is accepted. declare emits no runtime code, so the inherited getter is untouched and the declaration is purely a type-level assertion.

• Verify MatterbridgeEndpoint is imported as a type-only import, for example import type { MatterbridgeEndpoint } from '../matterbridgeEndpoint.js'. A value import creates an import cycle for every behavior that matterbridgeEndpointHelpers.ts imports.

• Verify no this.endpoint as MatterbridgeEndpoint assertion remains in scope, including the endpoint property of the device.commandHandler.executeHandler(...) payload.

• Verify a file-level /* oxlint-disable typescript/no-unsafe-type-assertion */ suppression is removed once the file contains no remaining type assertion. Keep it only when an unrelated assertion still requires it.

• Report a missing declaration, a remaining as MatterbridgeEndpoint assertion, a value import of MatterbridgeEndpoint, or an obsolete assertion suppression as an endpoint type narrowing violation.

Plugin forwarding contract:

• For every overridden Matter command handler in scope, verify that forwarding to the plugin through device.commandHandler.executeHandler(...) occurs immediately after the command-entry log.
• Before the forwarding call, allow only the minimal local lookup required to access the logger and command handler, such as const device = this.endpoint.stateOf(MatterbridgeServer), followed by the command-entry log.
• Verify only the command-entry log immediately before forwarding uses the info level, for example device.log.info(...). A command-entry log at debug, notice, warn, error, fatal, or any other level is not compliant.
• Do not require any other log to use info. Logs outside the command-entry position may use any appropriate log level, but their messages must still satisfy the server-name prefix and endpoint suffix rules.
• The forwarding call must be awaited before execution continues.
• Do not allow request validation, assertions, conditionals, early returns, thrown errors, state reads used for decisions, state changes, event emission, additional logging, or other side effects between the command-entry log and completion of the awaited forwarding call.
• Verify all validation and state mutation occur only after the awaited forwarding call.
• Report a missing command-entry log, command-entry log at a level other than info, missing forwarding call, non-awaited forwarding call, or any disallowed operation before forwarding completes as a plugin forwarding contract violation.
• Exempt from this contract the servers whose cluster has no entry in the CommandHandlers type of matterbridgeEndpointCommandHandler.ts, currently Chime, Camera AV Stream Management, Camera AV Settings User Level Management, WebRTC Transport Provider and WebRTC Transport Requestor. They reach the plugin only through the command observable, after validation, so they have no executeHandler(...) call; they must still log, validate and emit the command observable as required by the other sections. Do not report the missing forwarding call for these servers, and recheck the CommandHandlers type before applying the exemption to any other server.

Command observable emission:

• Verify every overridden Matter command handler in scope emits the command observable added by subscribeCommand() as the very last call of the handler:

  this.endpoint.emitCommand(OnOff, 'offWithEffect', request, this.context);

• Pass the cluster as the ClusterType exported by @matter/types/clusters/<cluster>, for example OnOff or BooleanStateConfiguration. Do not accept <Cluster>.Cluster, a behavior type, a behavior id such as OnOffServer.id, or a cluster name string: the ClusterType form keeps the command name and the request payload checked against the cluster definition.

• Pass the exact command name of the enclosing handler, the request payload, and this.context. Use {} as the payload for commands that take no request.

• Verify the call goes through the narrowed this.endpoint. Do not accept the emitCommand helper imported from matterbridgeEndpointHelpers.ts in a behavior that module imports, because the value import closes an import cycle.

• Verify the emission comes after the awaited plugin forwarding, after every validation, and after every state update, including after the await super.<command>() call when the handler delegates to the base implementation. No statement may follow it, except a final return of the command response in handlers that return one.

• That return may only hand back the response: an object literal, or a value already computed before the emission, such as const response = await super.<command>(request); returned after emitting. It must not call methods, read or change state, log, or have any other side effect. Do not accept a try/finally block used only to defer the emission past the return; emit first, then return.

  this.state.currentMode = request.newMode;
  this.endpoint.emitCommand(OvenMode, 'changeToMode', request, this.context);
  return { status: ModeBase.ModeChangeStatus.Success, statusText: 'Success' };

• Do not require an emission on a path that rejects the command with a Matter status error, discards it by cluster conformance, or returns early, for example the MATTERBRIDGE_CHIP_TEST branch that gates the plugin forwarder off. The observable reports commands that completed.

• Report a missing emission, an emission that is not the last call (a final side-effect-free return of the command response is allowed), an emission placed before validation or state updates, a cluster passed in any form other than the ClusterType, a command name that does not match the enclosing handler, a missing this.context, or a direct helper import as a command observable emission violation.