Skip to content

Commit f5c34f0

Browse files
Extensions: Compatibility guarantee
Signed-off-by: Ahmed Jamil <[email protected]>
1 parent c140f9f commit f5c34f0

6 files changed

Lines changed: 564 additions & 25 deletions

File tree

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
import {
2+
MESHERY_EXTENSION_CAPABILITIES,
3+
MESHERY_EXTENSION_CONTRACT_VERSION,
4+
MESHERY_EXTENSION_DEPRECATED_CAPABILITIES,
5+
MESHERY_EXTENSION_EVENT,
6+
MESHERY_EXTENSION_EVENT_TYPES,
7+
MESHERY_EXTENSION_HOOKS,
8+
describeInjectedCapabilityReport,
9+
isInjectedCapabilityReportSatisfied,
10+
isMesheryExtensionEvent,
11+
reportInjectedCapabilities
12+
} from '../actors/mesheryExtensionContract';
13+
14+
/** A host bag that satisfies the contract exactly, built from the contract itself. */
15+
const satisfyingInjectProps = () => ({
16+
...Object.fromEntries(MESHERY_EXTENSION_CAPABILITIES.map(key => [key, () => null])),
17+
hooks: Object.fromEntries(MESHERY_EXTENSION_HOOKS.map(hook => [hook, () => null]))
18+
});
19+
20+
describe('Meshery extension contract — event literals', () => {
21+
it('exposes a literal for every event type on the bus', () => {
22+
// The union -> map completeness guard is compile-time; this asserts the
23+
// runtime array stays in step with the map it is derived from.
24+
expect([...MESHERY_EXTENSION_EVENT_TYPES].sort()).toEqual(
25+
Object.values(MESHERY_EXTENSION_EVENT).sort()
26+
);
27+
});
28+
29+
it('pins the wire literals that cross the host boundary', () => {
30+
// Hard-coded on purpose. These strings are the actual contract: a rename is
31+
// only safe alongside a contract-version bump and a deprecation entry, and
32+
// this test is what forces that conversation. Renaming
33+
// OPEN_DESIGN_IN_KANVAS -> OPEN_DESIGN_IN_EXTENSION silently broke opening a
34+
// design because nothing pinned them.
35+
expect(MESHERY_EXTENSION_EVENT).toEqual({
36+
K8sContextsUpdated: 'K8S_CONTEXTS_UPDATED',
37+
OpenViewScopedToDesign: 'OPEN_VIEW_SCOPED_TO_DESIGN',
38+
OpenDesignInExtension: 'OPEN_DESIGN_IN_EXTENSION',
39+
OpenViewInExtension: 'OPEN_VIEW_IN_EXTENSION',
40+
MergeDesign: 'MERGE_DESIGN',
41+
DispatchToMesheryStore: 'DISPATCH_TO_MESHERY_STORE',
42+
FeatureRequiresUserAccount: 'FeatureRequiresUserAccount',
43+
MissingPermission: 'MISSING_PERMISSION',
44+
MissingCapability: 'MISSING_CAPABILITY'
45+
});
46+
});
47+
48+
it('recognises contract events and rejects unknown literals', () => {
49+
expect(
50+
isMesheryExtensionEvent({
51+
type: MESHERY_EXTENSION_EVENT.OpenDesignInExtension,
52+
data: { designId: 'd', designName: 'n' }
53+
})
54+
).toBe(true);
55+
// The pre-fix literal. A subscriber that receives this is talking to a host
56+
// built against a different contract and must say so rather than no-op.
57+
expect(isMesheryExtensionEvent({ type: 'OPEN_DESIGN_IN_KANVAS', data: {} })).toBe(false);
58+
});
59+
60+
it('rejects non-event values without throwing', () => {
61+
expect(isMesheryExtensionEvent(null)).toBe(false);
62+
expect(isMesheryExtensionEvent(undefined)).toBe(false);
63+
expect(isMesheryExtensionEvent('OPEN_DESIGN_IN_EXTENSION')).toBe(false);
64+
expect(isMesheryExtensionEvent({})).toBe(false);
65+
});
66+
});
67+
68+
describe('Meshery extension contract — injected capabilities', () => {
69+
it('reports a fully-satisfying host as satisfied', () => {
70+
const report = reportInjectedCapabilities(satisfyingInjectProps());
71+
72+
expect(report.missing).toEqual([]);
73+
expect(report.missingHooks).toEqual([]);
74+
expect(isInjectedCapabilityReportSatisfied(report)).toBe(true);
75+
expect(describeInjectedCapabilityReport(report)).toBeNull();
76+
});
77+
78+
it('names the capability a host stopped injecting', () => {
79+
// This is the capabilitiesRegistry -> providerCapabilities incident in
80+
// miniature: the host drops a key, every read yields undefined, and the
81+
// failure used to surface as an unrelated crash far from the cause.
82+
const injectProps = satisfyingInjectProps();
83+
delete (injectProps as Record<string, unknown>).providerCapabilities;
84+
85+
const report = reportInjectedCapabilities(injectProps);
86+
87+
expect(report.missing).toEqual(['providerCapabilities']);
88+
expect(isInjectedCapabilityReportSatisfied(report)).toBe(false);
89+
expect(describeInjectedCapabilityReport(report)).toContain('providerCapabilities');
90+
});
91+
92+
it('names a missing nested hook', () => {
93+
const injectProps = { ...satisfyingInjectProps(), hooks: { CAN: () => true } };
94+
95+
const report = reportInjectedCapabilities(injectProps);
96+
97+
expect(report.missingHooks).toEqual(['useDynamicComponent', 'useFilterK8sContexts']);
98+
expect(describeInjectedCapabilityReport(report)).toContain('useFilterK8sContexts');
99+
});
100+
101+
it('does not double-report hooks when the whole hooks bag is absent', () => {
102+
const injectProps = satisfyingInjectProps();
103+
delete (injectProps as Record<string, unknown>).hooks;
104+
105+
const report = reportInjectedCapabilities(injectProps);
106+
107+
expect(report.missing).toContain('hooks');
108+
expect(report.missingHooks).toEqual([]);
109+
});
110+
111+
it('flags deprecated aliases alongside their replacement without failing the check', () => {
112+
const report = reportInjectedCapabilities({
113+
...satisfyingInjectProps(),
114+
capabilitiesRegistry: {},
115+
CapabilitiesRegistryClass: class {}
116+
});
117+
118+
expect(report.deprecated).toEqual([
119+
{ provided: 'capabilitiesRegistry', replacement: 'providerCapabilities' },
120+
{ provided: 'CapabilitiesRegistryClass', replacement: 'ProviderUiAccessControlClass' }
121+
]);
122+
// Legacy bundles still depend on these, so their presence is informational.
123+
expect(isInjectedCapabilityReportSatisfied(report)).toBe(true);
124+
});
125+
126+
it('does not report the host handshake field as an unknown key', () => {
127+
// The host advertises `contractVersion` on the same bag. Reporting the
128+
// host's own handshake field as unrecognized is noise, and noise is what
129+
// trains people to stop reading the report.
130+
const report = reportInjectedCapabilities({
131+
...satisfyingInjectProps(),
132+
contractVersion: MESHERY_EXTENSION_CONTRACT_VERSION
133+
});
134+
135+
expect(report.unrecognized).toEqual([]);
136+
});
137+
138+
it('reports keys this build has never heard of as unrecognized', () => {
139+
const report = reportInjectedCapabilities({
140+
...satisfyingInjectProps(),
141+
someCapabilityFromANewerHost: () => null
142+
});
143+
144+
expect(report.unrecognized).toEqual(['someCapabilityFromANewerHost']);
145+
expect(isInjectedCapabilityReportSatisfied(report)).toBe(true);
146+
});
147+
148+
it('treats a null or undefined bag as every capability missing', () => {
149+
for (const bag of [null, undefined]) {
150+
const report = reportInjectedCapabilities(bag);
151+
expect(report.missing).toEqual([...MESHERY_EXTENSION_CAPABILITIES]);
152+
expect(describeInjectedCapabilityReport(report)).toContain('contract');
153+
}
154+
});
155+
156+
it('keeps every deprecated alias pointing at a real capability or an outright removal', () => {
157+
for (const replacement of Object.values(MESHERY_EXTENSION_DEPRECATED_CAPABILITIES)) {
158+
if (replacement === null) continue;
159+
expect(MESHERY_EXTENSION_CAPABILITIES).toContain(replacement);
160+
}
161+
});
162+
163+
it('never lists a deprecated alias as a current capability', () => {
164+
for (const alias of Object.keys(MESHERY_EXTENSION_DEPRECATED_CAPABILITIES)) {
165+
expect(MESHERY_EXTENSION_CAPABILITIES).not.toContain(alias);
166+
}
167+
});
168+
});
169+
170+
describe('Meshery extension contract — version', () => {
171+
it('is a positive integer hosts and extensions can compare', () => {
172+
expect(Number.isInteger(MESHERY_EXTENSION_CONTRACT_VERSION)).toBe(true);
173+
expect(MESHERY_EXTENSION_CONTRACT_VERSION).toBeGreaterThan(0);
174+
});
175+
});

‎src/actors/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,5 @@ export {
3939
} from './utils';
4040

4141
export * from './eventBus';
42+
43+
export * from './mesheryExtensionContract';

0 commit comments

Comments
 (0)