Matt Gilman created NIFI-16395:
----------------------------------
Summary: Define canonical TypeScript entity and request contracts
for canvas components
Key: NIFI-16395
URL: https://issues.apache.org/jira/browse/NIFI-16395
Project: Apache NiFi
Issue Type: Task
Components: Core UI
Reporter: Matt Gilman
h2. Background
The connector canvas currently stores component collections as any[] and relies
on loosely typed objects across state, rendering, and interaction boundaries.
Several copies of shared primitives such as Position also exist in separate
canvas modules.
Before connector canvas editing is expanded, the frontend needs canonical
TypeScript contracts that accurately represent NiFi REST response entities and
write requests.
h2. Goals
* Establish one canonical TypeScript model for each canvas component entity.
* Consolidate shared canvas primitives.
* Distinguish server response entities from client write payloads.
* Model denied-read responses without weakening fields that NiFi always returns.
* Provide a stable type foundation for connector state and reusable-canvas work.
h2. Scope
h3. Shared Primitives
* Define a canonical Position interface in the shared library.
* Reuse the existing canonical Revision and Permissions interfaces.
* Replace duplicate Position declarations and update their consumers.
* Introduce RevisionRequest for write operations that do not include
response-only revision fields.
h3. Entity Contracts
Add canonical response contracts for:
* ComponentEntityBase
* PositionableComponentEntityBase
* ProcessorEntity
* ConnectionEntity
* PortEntity
* ProcessGroupEntity
* RemoteProcessGroupEntity
* FunnelEntity
* LabelEntity
Include the component DTOs, status DTOs, and nested DTO contracts required to
model these entities without any or open-ended index signatures.
h3. Request Contracts
Define typed request projections for canvas write operations, including:
* Component creation.
* Component position updates.
* Connection bend and label-index updates.
* Connection destination updates.
* Component run-status requests.
* Snippet-based move and delete operations.
Write contracts should derive field types from canonical response contracts
with Pick, Omit, Partial, or equivalent utility types where practical. Response
contracts must not be weakened to accommodate partial write bodies.
h2. Contract Rules
* Java DTOs, entity factories, and resource response behavior are the source of
truth.
* Fields populated on every response are required.
* The component body is optional because it can be omitted when the user lacks
read permission.
* Response-only fields must not appear in create or update request contracts.
* Dynamic index signatures such as [key: string]: unknown are not permitted on
canonical entity contracts.
* Canvas entity contracts must not use explicit any.
* Connections remain non-positionable and use bends and labelIndex for geometry.
* Input and output ports share PortEntity and are distinguished by their port
type.
h2. Out of Scope
* Migrating connector canvas state collections to the new entity contracts.
* Retyping reusable-canvas renderers and gestures.
* Changing REST endpoint behavior or Java DTOs.
* Changing connector troubleshooting behavior.
* Migrating the legacy flow-designer canvas.
h2. Acceptance Criteria
* A canonical shared Position type replaces the duplicate frontend definitions.
* Canonical response entities exist for all seven canvas component kinds.
* Entity requiredness matches NiFi resource and factory behavior.
* Unreadable entities can omit component while retaining the required envelope
fields.
* Typed write contracts are separate from response entity contracts.
* Connection geometry and destination updates have dedicated typed payloads.
* No canonical entity contains explicit any or an open-ended index signature.
* Existing consumers compile after primitive consolidation.
* Type-focused tests or fixtures cover readable and unreadable entity shapes.
* Frontend lint, strict type-check, unit tests, and production build pass.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
