@balena/compose-parser 0.0.2-build-setup-compose-go-1206dd03ac7e912df0da255a5bbf3d40cb932da1-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/compose.ts ADDED
@@ -0,0 +1,832 @@
1
+ import { exec as execSync } from 'child_process';
2
+ import { promisify } from 'util';
3
+ import { randomUUID } from 'crypto';
4
+ import * as path from 'path';
5
+ import { validRange } from 'semver';
6
+
7
+ import {
8
+ ComposeError,
9
+ ValidationError,
10
+ ArgumentError,
11
+ ServiceError,
12
+ } from './errors';
13
+ import type {
14
+ Composition,
15
+ Dict,
16
+ Service,
17
+ BuildConfig,
18
+ Network,
19
+ Volume,
20
+ DevicesConfig,
21
+ ServiceVolumeConfig,
22
+ ContractObject,
23
+ ImageDescriptor,
24
+ } from './types';
25
+
26
+ const exec = promisify(execSync);
27
+
28
+ /**
29
+ * Parse one or more compose files using compose-go, and return a normalized composition object
30
+ * @param composeFilePaths - Path(s) to the compose file(s) to parse. Can be a single string or an array of strings.
31
+ * @returns Normalized composition object
32
+ */
33
+ export async function parse(
34
+ composeFilePaths: string | string[],
35
+ ): Promise<Composition> {
36
+ // Normalize input to always be an array
37
+ const filePaths = Array.isArray(composeFilePaths)
38
+ ? composeFilePaths
39
+ : [composeFilePaths];
40
+
41
+ // Validate that at least one file path is provided
42
+ if (filePaths.length === 0) {
43
+ throw new ArgumentError('At least one compose file path must be provided');
44
+ }
45
+
46
+ // Use a random UUID as the project name so it's easy to remove later,
47
+ // as balena doesn't use the project name, but compose-go injects it in several places.
48
+ const projectName = randomUUID();
49
+
50
+ // Build the command with -f flags for each file
51
+ const fileFlags = filePaths.map((filePath) => `-f ${filePath}`).join(' ');
52
+
53
+ const binaryPath = path.join(__dirname, '..', 'bin', 'balena-compose-go');
54
+ const result = await exec(`${binaryPath} ${fileFlags} ${projectName}`, {
55
+ env: process.env,
56
+ }).catch((e) => {
57
+ // If exec error has stdout/stderr, handle them later; otherwise throw immediately
58
+ if (e.stdout !== undefined && e.stderr !== undefined) {
59
+ return e;
60
+ }
61
+ throw e;
62
+ });
63
+
64
+ const { stdout, stderr } = result;
65
+
66
+ if (stderr) {
67
+ // Compose-go logs warnings to stderr, and we don't need to throw for those. Just ignore them for now.
68
+ // TODO: Revisit ignoring warnings once we achieve maximum compose spec v2 support
69
+ const errorsOrWarnings = toComposeError(stderr);
70
+ const errors = errorsOrWarnings.filter((e: ComposeError) =>
71
+ ['error', 'fatal', 'panic'].includes(e.level),
72
+ );
73
+ // Only throw the first error
74
+ if (errors.length > 0) {
75
+ throw errors[0];
76
+ }
77
+ }
78
+
79
+ // Parse the stdout directly as the composition data
80
+ const parsedResult = JSON.parse(stdout) as Dict<any>;
81
+
82
+ // Normalize raw composition into a balena-acceptable composition
83
+ // Use the first file path as the base for relative path calculations
84
+ return normalize(parsedResult, filePaths[0]);
85
+ }
86
+
87
+ /**
88
+ * Convert stderr output from compose-go into a list of ComposeError objects
89
+ * @param stderr - stderr string output from compose-go
90
+ * @returns List of ComposeErrors
91
+ */
92
+ function toComposeError(stderr: string): ComposeError[] {
93
+ const errors: ComposeError[] = [];
94
+ const lines = stderr.split('\n').filter((line) => line.trim() !== '');
95
+ lines.forEach((line) => {
96
+ try {
97
+ const parsed = JSON.parse(line);
98
+
99
+ // Both our custom error format and logrus JSON format have 'message' field
100
+ if (parsed.message) {
101
+ errors.push(
102
+ new ComposeError(
103
+ parsed.message,
104
+ parsed.level ?? 'error',
105
+ parsed.name,
106
+ ),
107
+ );
108
+ }
109
+ } catch {
110
+ // If JSON parsing fails, warn and skip this line
111
+ console.warn(`Could not parse stderr line as JSON: ${line}`);
112
+ }
113
+ });
114
+ return errors;
115
+ }
116
+
117
+ function normalize(
118
+ rawComposition: Dict<any>,
119
+ composeFilePath: string,
120
+ ): Composition {
121
+ const composition: Composition = {
122
+ services: {},
123
+ };
124
+
125
+ // Balena doesn't make use of the project name, but it's injected into the
126
+ // names of networks and volumes by compose-go, so must be removed.
127
+ if (rawComposition.name) {
128
+ removeProjectName(rawComposition, rawComposition.name);
129
+ }
130
+
131
+ // Reject top-level secrets & configs
132
+ if (rawComposition.secrets || rawComposition.configs) {
133
+ throw new ValidationError(
134
+ 'Top-level secrets and/or configs are not supported',
135
+ );
136
+ }
137
+
138
+ if (rawComposition.services) {
139
+ for (const [serviceName, service] of Object.entries(
140
+ rawComposition.services,
141
+ )) {
142
+ composition.services[serviceName] = normalizeService(
143
+ service as Dict<any>,
144
+ composeFilePath,
145
+ serviceName,
146
+ );
147
+ }
148
+ }
149
+
150
+ if (rawComposition.networks) {
151
+ composition.networks = {};
152
+ for (const [networkName, network] of Object.entries(
153
+ rawComposition.networks,
154
+ )) {
155
+ composition.networks[networkName] = normalizeNetwork(
156
+ network as Dict<any>,
157
+ );
158
+ }
159
+ }
160
+
161
+ if (rawComposition.volumes) {
162
+ composition.volumes = {};
163
+ for (const [volumeName, volume] of Object.entries(rawComposition.volumes)) {
164
+ composition.volumes[volumeName] = normalizeVolume(volume as Dict<any>);
165
+ }
166
+ }
167
+
168
+ return composition;
169
+ }
170
+
171
+ /**
172
+ * Remove project name based on top-level `name` key, and any nested values that
173
+ * contain the project name. compose-go injects the project name into the composition
174
+ * in network.name and volume.name (and possibly elsewhere), which aren't used by balena
175
+ * as the Supervisor uses its own naming scheme for networks and volumes.
176
+ * @param obj - Composition object to remove project name from
177
+ * @param projectName - Project name to remove
178
+ */
179
+ function removeProjectName(obj: Dict<any>, projectName: string) {
180
+ const stack: Array<Dict<any>> = [obj];
181
+
182
+ while (stack.length > 0) {
183
+ const current = stack.pop()!;
184
+
185
+ for (const [key, value] of Object.entries(current)) {
186
+ if (typeof value === 'object' && value) {
187
+ stack.push(value);
188
+ } else if (typeof value === 'string' && value.includes(projectName)) {
189
+ delete current[key];
190
+ }
191
+ }
192
+ }
193
+ }
194
+
195
+ export const SERVICE_CONFIG_DENY_LIST = [
196
+ 'blkio_config',
197
+ 'configs',
198
+ 'cpu_count',
199
+ 'cpu_percent',
200
+ 'cpu_period',
201
+ // 'cpu_quota', // TODO: Currently supported, but should remove support as kernel 6.6+ does not use CFS which this configures
202
+ 'credential_spec',
203
+ 'deploy',
204
+ 'develop',
205
+ 'external_links',
206
+ 'gpus',
207
+ 'isolation',
208
+ 'links',
209
+ 'logging',
210
+ 'mem_swappiness',
211
+ 'memswap_limit',
212
+ 'oom_kill_disable',
213
+ 'platform',
214
+ // TODO: Currently compose-go does not include a service with profiles set if they're not specified in COMPOSE_PROFILES,
215
+ // so a composition with profiles doesn't actually reject as the profiles are not added to the parsed compose by compose-go.
216
+ // We should support profiles which will involve modifying this code, but in dedicated shaping + building cycles.
217
+ // 'profiles',
218
+ 'pull_policy',
219
+ 'runtime',
220
+ 'scale',
221
+ 'secrets',
222
+ 'stdin_open',
223
+ 'storage_opt',
224
+ ];
225
+
226
+ const OOM_SCORE_ADJ_WARN_THRESHOLD = -900;
227
+
228
+ const bindMountByLabel: Array<[string, string[]]> = [
229
+ ['io.balena.features.balena-socket', ['/var/run/docker.sock']],
230
+ ['io.balena.features.balena-socket', ['/var/run/balena-engine.sock']],
231
+ ['io.balena.features.dbus', ['/run/dbus']],
232
+ ['io.balena.features.sysfs', ['/sys']],
233
+ ['io.balena.features.procfs', ['/proc']],
234
+ ['io.balena.features.kernel-modules', ['/lib/modules']],
235
+ ['io.balena.features.firmware', ['/lib/firmware']],
236
+ [
237
+ 'io.balena.features.journal-logs',
238
+ ['/var/log/journal', '/run/log/journal', '/etc/machine-id'],
239
+ ],
240
+ ];
241
+
242
+ const allowedBindMounts = bindMountByLabel.flatMap(
243
+ ([_, appliedBindMounts]) => appliedBindMounts,
244
+ );
245
+
246
+ function normalizeService(
247
+ rawService: Dict<any>,
248
+ composeFilePath: string,
249
+ serviceName: string,
250
+ ): Service {
251
+ const service: Service = { ...rawService };
252
+
253
+ // Reject if unsupported fields are present
254
+ for (const field of SERVICE_CONFIG_DENY_LIST) {
255
+ if (field in service) {
256
+ throw new ServiceError(`service.${field} is not allowed`, serviceName);
257
+ }
258
+ }
259
+
260
+ if (rawService.build) {
261
+ service.build = normalizeServiceBuild(
262
+ rawService.build,
263
+ composeFilePath,
264
+ serviceName,
265
+ );
266
+ }
267
+
268
+ // Reject if io.balena.private namespace is used for labels
269
+ if (service.labels) {
270
+ validateLabels(service.labels, serviceName);
271
+ }
272
+
273
+ // Reject network_mode:container:${containerId} as we don't support this
274
+ if (service.network_mode?.match(/^container:.*$/)) {
275
+ throw new ServiceError(
276
+ 'service.network_mode container:${containerId} is not allowed',
277
+ serviceName,
278
+ );
279
+ }
280
+
281
+ // Reject pid:container:${containerId} as we don't support this
282
+ if (service.pid?.match(/^container:.*$/)) {
283
+ throw new ServiceError(
284
+ 'service.pid container:${containerId} is not allowed',
285
+ serviceName,
286
+ );
287
+ }
288
+
289
+ // Reject all security_opt settings except no-new-privileges
290
+ if (service.security_opt?.some((opt) => !opt.match('no-new-privileges'))) {
291
+ throw new ServiceError(
292
+ 'Only no-new-privileges is allowed for service.security_opt',
293
+ serviceName,
294
+ );
295
+ }
296
+
297
+ // Reject volumes_from which references container:${containerId}
298
+ if (service.volumes_from?.some((v) => v.match(/^container:.*$/))) {
299
+ throw new ServiceError(
300
+ 'service.volumes_from which references a containerId is not allowed',
301
+ serviceName,
302
+ );
303
+ }
304
+
305
+ // Remove null entrypoint
306
+ /// compose-go adds `entrypoint: null` if entrypoint is unspecified.
307
+ /// In docker-compose, this means that the default entrypoint from the image is used, but in
308
+ /// balena, it overrides any ENTRYPOINT directive in the Dockerfile.
309
+ /// See: https://docs.docker.com/reference/compose-file/services/#entrypoint
310
+ if (service.entrypoint === null) {
311
+ delete service.entrypoint;
312
+ }
313
+
314
+ // Convert long syntax ports to short syntax
315
+ /// compose-go converts all port definitions to long syntax, however legacy Supervisors don't support this.
316
+ /// TODO: Support this in Helios
317
+ if (service.ports) {
318
+ service.ports = longToShortSyntaxPorts(service.ports);
319
+ }
320
+
321
+ // Convert long syntax depends_on to short syntax
322
+ /// compose-go converts all depends_on definitions to long syntax, however legacy Supervisors don't support this.
323
+ /// TODO: Support this in Helios
324
+ if (service.depends_on) {
325
+ service.depends_on = longToShortSyntaxDependsOn(service.depends_on);
326
+ }
327
+
328
+ // Convert long syntax devices to short syntax
329
+ /// compose-go converts all devices definitions to long syntax, however legacy Supervisors don't support this.
330
+ /// TODO: Support this in Helios
331
+ if (service.devices) {
332
+ service.devices = longToShortSyntaxDevices(
333
+ service.devices as DevicesConfig[],
334
+ serviceName,
335
+ );
336
+ }
337
+
338
+ if (service.volumes) {
339
+ // At this point, service.volumes hasn't been converted to string[]
340
+ // so it's safe to cast to ServiceVolumeConfig[], as compose-go converts
341
+ // all volumes definitions to long syntax.
342
+ const v = service.volumes as ServiceVolumeConfig[];
343
+
344
+ // Convert allowed bind mounts to labels
345
+ const labels = allowedBindMountsToLabels(v);
346
+
347
+ if (labels.length > 0) {
348
+ service.labels = {
349
+ ...service.labels,
350
+ ...Object.fromEntries(labels.map((label) => [label, '1'])),
351
+ };
352
+ }
353
+
354
+ // Convert long syntax volumes to short syntax
355
+ /// compose-go converts all volumes definitions to long syntax, however legacy Supervisors don't support this.
356
+ /// TODO: Support this in Helios
357
+ const { shortSyntaxVolumes, shortSyntaxTmpfs } = longToShortSyntaxVolumes(
358
+ v,
359
+ serviceName,
360
+ );
361
+ if (shortSyntaxVolumes.length > 0) {
362
+ service.volumes = shortSyntaxVolumes;
363
+ } else {
364
+ delete service.volumes;
365
+ }
366
+ if (shortSyntaxTmpfs.length > 0) {
367
+ service.tmpfs = [...(service.tmpfs ?? []), ...shortSyntaxTmpfs];
368
+ }
369
+ }
370
+
371
+ // Add image as build tag if present
372
+ if (service.image && service.build) {
373
+ service.build.tags = [...(service.build.tags ?? []), service.image];
374
+ }
375
+
376
+ // Delete env_file, as compose-go adds env_file vars to service.environment
377
+ delete service.env_file;
378
+
379
+ // Delete label_file, as compose-go adds label_file labels to service.labels
380
+ delete service.label_file;
381
+
382
+ // Warn that expose is informational only
383
+ if (service.expose) {
384
+ console.warn(
385
+ 'service.expose is informational only. Removing from the composition',
386
+ );
387
+ delete service.expose;
388
+ }
389
+
390
+ // Warn of risks of breaking device functionality with oom_score_adj <= OOM_SCORE_ADJ_WARN_THRESHOLD
391
+ if (
392
+ service.oom_score_adj &&
393
+ service.oom_score_adj <= OOM_SCORE_ADJ_WARN_THRESHOLD
394
+ ) {
395
+ console.warn(
396
+ `service.oom_score_adj values under ${OOM_SCORE_ADJ_WARN_THRESHOLD} may break device functionality`,
397
+ );
398
+ }
399
+
400
+ // Warn that container_name is not supported and remove it
401
+ if (service.container_name) {
402
+ console.warn(
403
+ 'service.container_name is not supported. Removing from the composition',
404
+ );
405
+ delete service.container_name;
406
+ }
407
+
408
+ return service;
409
+ }
410
+
411
+ export const BUILD_CONFIG_DENY_LIST = [
412
+ 'additional_contexts',
413
+ 'cache_to',
414
+ 'dockerfile_inline',
415
+ 'entitlements',
416
+ 'isolation',
417
+ 'network',
418
+ 'no_cache',
419
+ 'platforms',
420
+ 'privileged',
421
+ 'pull',
422
+ 'secrets',
423
+ 'ssh',
424
+ 'tags',
425
+ 'ulimits',
426
+ ];
427
+
428
+ function normalizeServiceBuild(
429
+ rawServiceBuild: Dict<any>,
430
+ composeFilePath: string,
431
+ serviceName: string,
432
+ ): BuildConfig {
433
+ const build: BuildConfig = { ...rawServiceBuild };
434
+
435
+ // Reject if unsupported fields are present
436
+ for (const field of BUILD_CONFIG_DENY_LIST) {
437
+ if (field in build) {
438
+ throw new ServiceError(
439
+ `service.build.${field} is not allowed`,
440
+ serviceName,
441
+ );
442
+ }
443
+ }
444
+
445
+ // Reject if io.balena.private namespace is used for labels
446
+ if (build.labels) {
447
+ validateLabels(build.labels, serviceName);
448
+ }
449
+
450
+ // Convert absolute context paths to relative paths
451
+ /// compose-go converts relative context to absolute, but the existing image build methods
452
+ /// in balena-compose rely on relative paths.
453
+ if (build.context) {
454
+ /// Reject if remote context (ends with .git) as we don't currently support this
455
+ if (build.context.endsWith('.git')) {
456
+ throw new ServiceError(
457
+ `service.build.context cannot be a remote context`,
458
+ serviceName,
459
+ );
460
+ }
461
+
462
+ build.context =
463
+ path.relative(path.dirname(composeFilePath), build.context) || '.';
464
+ }
465
+ return build;
466
+ }
467
+
468
+ const NAMESPACED_LABEL_ERROR_MESSAGE =
469
+ 'labels cannot use the "io.balena.private" namespace';
470
+ function validateLabels(labels: Dict<any>, serviceName?: string) {
471
+ for (const [name, value] of Object.entries(labels)) {
472
+ // Reject io.balena.private label namespace
473
+ if (name.startsWith('io.balena.private')) {
474
+ if (serviceName) {
475
+ throw new ServiceError(NAMESPACED_LABEL_ERROR_MESSAGE, serviceName);
476
+ } else {
477
+ throw new ValidationError(NAMESPACED_LABEL_ERROR_MESSAGE);
478
+ }
479
+ }
480
+
481
+ // Validate contract labels
482
+ if (name.startsWith(contractRequirementLabelPrefix)) {
483
+ const ctype = name.replace(contractRequirementLabelPrefix, '');
484
+ if (ctype in supportedContractRequirementLabels) {
485
+ supportedContractRequirementLabels[ctype].validate(value, name);
486
+ }
487
+ }
488
+ }
489
+ }
490
+
491
+ function longToShortSyntaxPorts(
492
+ ports: NonNullable<Service['ports']>,
493
+ ): string[] {
494
+ const shortSyntaxPorts: string[] = [];
495
+ const ignoredFields = ['name', 'app_protocol', 'mode'];
496
+
497
+ for (const port of ports) {
498
+ if (typeof port === 'string') {
499
+ shortSyntaxPorts.push(port);
500
+ } else if (typeof port === 'object') {
501
+ // All long syntax configs are convertible to short syntax,
502
+ // but some fields in long syntax are ignored if present:
503
+ // - name: ignored as it doesn't serve a purpose in the service besides documentation
504
+ // - app_protocol: ignored
505
+ // - mode: ignored as we don't support Swarm features
506
+ // See: https://docs.docker.com/reference/compose-file/services/#long-syntax-4
507
+ for (const field of ignoredFields) {
508
+ if (field in port) {
509
+ console.warn(
510
+ `service.ports.${field} is not supported. Removing from the composition`,
511
+ );
512
+ delete (port as any)[field];
513
+ }
514
+ }
515
+ shortSyntaxPorts.push(
516
+ (port.host_ip ? `${port.host_ip}:` : '') +
517
+ `${port.published ? `${port.published}:` : ''}${port.target}` +
518
+ // Only include protocol if it's not default (not TCP)
519
+ (port.protocol !== 'tcp' ? `/${port.protocol}` : ''),
520
+ );
521
+ }
522
+ }
523
+
524
+ return shortSyntaxPorts;
525
+ }
526
+
527
+ function longToShortSyntaxDependsOn(
528
+ dependsOn: NonNullable<Service['depends_on']>,
529
+ ): string[] {
530
+ const shortSyntaxDependsOn: string[] = [];
531
+
532
+ for (const [serviceName, dependsOnConfig] of Object.entries(dependsOn)) {
533
+ // Some dependsOnConfigs are not convertible to short syntax, and may define a different depends_on behavior
534
+ // than the short syntax default. We don't support long syntax depends_on in legacy Supervisors, so warn for now
535
+ // and convert to short syntax although the dependency behavior is slightly different.
536
+ // Short syntax depends_on is equivalent to long syntax condition: service_started and required: true
537
+ if (
538
+ dependsOnConfig.condition !== 'service_started' ||
539
+ dependsOnConfig.required !== true
540
+ ) {
541
+ throw new ServiceError(
542
+ `Long syntax depends_on ${JSON.stringify(dependsOnConfig)} ` +
543
+ `for service "${serviceName}" or a definition that generates ` +
544
+ 'a long syntax depends_on config is not yet supported, ' +
545
+ 'using short syntax to express dependency',
546
+ serviceName,
547
+ );
548
+ }
549
+
550
+ // If required is false, the service is optional, so we don't need to express a dependency
551
+ // TODO: Compose warns if service isn't started or available if required=false.
552
+ // Supervisor will need to warn once it supports long syntax depends_on.
553
+ if (dependsOnConfig.required !== false) {
554
+ shortSyntaxDependsOn.push(serviceName);
555
+ }
556
+ }
557
+
558
+ return shortSyntaxDependsOn;
559
+ }
560
+
561
+ function longToShortSyntaxDevices(
562
+ devices: NonNullable<DevicesConfig[]>,
563
+ serviceName: string,
564
+ ): string[] {
565
+ const shortSyntaxDevices: string[] = [];
566
+ const CDIRegex = new RegExp('^(?!/)');
567
+
568
+ for (const deviceConfig of devices) {
569
+ // Reject if CDI syntax is used, we don't intend to support this
570
+ if (
571
+ CDIRegex.test(deviceConfig.source) ||
572
+ CDIRegex.test(deviceConfig.target)
573
+ ) {
574
+ throw new ServiceError(
575
+ `devices config with CDI syntax is not allowed`,
576
+ serviceName,
577
+ );
578
+ }
579
+
580
+ shortSyntaxDevices.push(
581
+ `${deviceConfig.source}:${deviceConfig.target}:${deviceConfig.permissions}`,
582
+ );
583
+ }
584
+
585
+ return shortSyntaxDevices;
586
+ }
587
+
588
+ function allowedBindMountsToLabels(volumes: ServiceVolumeConfig[]): string[] {
589
+ const labels: string[] = [];
590
+ bindMountByLabel.forEach(([label, appliedBindMounts]) => {
591
+ // EVERY bind mount associated with the label must be present for the label to be applied,
592
+ // except in the case of balena-engine label which only requires one of either bind mount
593
+ if (
594
+ appliedBindMounts.every((m) =>
595
+ volumes.some((v) => v.source && v.source === m),
596
+ )
597
+ ) {
598
+ labels.push(label);
599
+ }
600
+ });
601
+ return labels;
602
+ }
603
+
604
+ function longToShortSyntaxVolumes(
605
+ volumes: ServiceVolumeConfig[],
606
+ serviceName: string,
607
+ ): { shortSyntaxVolumes: string[]; shortSyntaxTmpfs: string[] } {
608
+ const shortSyntaxVolumes: string[] = [];
609
+ const shortSyntaxTmpfs: string[] = [];
610
+
611
+ for (const v of volumes) {
612
+ // Ignore allowed bind mounts as they're converted to labels separately
613
+ if (v.source && allowedBindMounts.includes(v.source)) {
614
+ continue;
615
+ }
616
+
617
+ // Reject volumes of type bind, image, npipe, or cluster
618
+ if (['bind', 'image', 'npipe', 'cluster'].includes(v.type)) {
619
+ throw new ServiceError(
620
+ `service.volumes cannot be of type "${v.type}"`,
621
+ serviceName,
622
+ );
623
+ }
624
+
625
+ // Reject volumes if options are specified that can't be converted to short syntax
626
+ const isLongSyntaxTmpfs =
627
+ v.type === 'tmpfs' && v.tmpfs && Object.keys(v.tmpfs).length > 0;
628
+ const isLongSyntaxVolume =
629
+ v.type === 'volume' && v.volume && Object.keys(v.volume).length > 0;
630
+ if (isLongSyntaxTmpfs || isLongSyntaxVolume) {
631
+ throw new ServiceError(
632
+ `long syntax service.volumes are not supported`,
633
+ serviceName,
634
+ );
635
+ }
636
+
637
+ if (v.type === 'volume' && (!v.source || !v.target)) {
638
+ throw new ServiceError(
639
+ `service.volumes ${JSON.stringify(v)} must specify source and target`,
640
+ serviceName,
641
+ );
642
+ }
643
+
644
+ if (v.type === 'volume') {
645
+ shortSyntaxVolumes.push(
646
+ `${v.source}:${v.target}${v.read_only ? ':ro' : ''}`,
647
+ );
648
+ } else if (v.type === 'tmpfs' && v.target) {
649
+ shortSyntaxTmpfs.push(v.target);
650
+ }
651
+ }
652
+
653
+ return { shortSyntaxVolumes, shortSyntaxTmpfs };
654
+ }
655
+
656
+ export const NETWORK_CONFIG_DENY_LIST = ['attachable', 'external', 'name'];
657
+
658
+ function normalizeNetwork(rawNetwork: Dict<any>): Network {
659
+ const network: Network = { ...rawNetwork };
660
+
661
+ // Reject if unsupported fields are present
662
+ for (const field of NETWORK_CONFIG_DENY_LIST) {
663
+ if (field in network) {
664
+ throw new ValidationError(`network.${field} is not allowed`);
665
+ }
666
+ }
667
+
668
+ // Reject if driver is not bridge
669
+ if (network.driver && !['bridge', 'default'].includes(network.driver)) {
670
+ throw new ValidationError(
671
+ `Only "bridge" and "default" are supported for network.driver, got "${network.driver}"`,
672
+ );
673
+ }
674
+
675
+ // Reject if `io.balena.private` namespace is used for labels
676
+ if (network.labels) {
677
+ validateLabels(network.labels);
678
+ }
679
+
680
+ // Warn if com.docker.network.bridge.name driver_opts is present as it may interfere with device firewall
681
+ if (network.driver_opts?.['com.docker.network.bridge.name']) {
682
+ console.warn(
683
+ 'com.docker.network.bridge.name network.driver_opt may interfere with device firewall',
684
+ );
685
+ }
686
+
687
+ return network;
688
+ }
689
+
690
+ export const VOLUME_CONFIG_DENY_LIST = ['external', 'name'];
691
+
692
+ function normalizeVolume(rawVolume: Dict<any>): Volume {
693
+ const volume: Volume = { ...rawVolume };
694
+
695
+ // Reject if non-local driver is used
696
+ if (volume.driver && !['local', 'default'].includes(volume.driver)) {
697
+ throw new ValidationError(
698
+ `Only "local" and "default" are supported for volume.driver, got "${volume.driver}"`,
699
+ );
700
+ }
701
+
702
+ // Reject if unsupported fields are present
703
+ for (const field of VOLUME_CONFIG_DENY_LIST) {
704
+ if (field in volume) {
705
+ throw new ValidationError(`volume.${field} is not allowed`);
706
+ }
707
+ }
708
+
709
+ // Reject if `io.balena.private` namespace is used for labels
710
+ if (volume.labels) {
711
+ validateLabels(volume.labels);
712
+ }
713
+
714
+ return volume;
715
+ }
716
+
717
+ interface ContractParser {
718
+ validate(value: string, label: string): void;
719
+ transform(value: string): ContractObject;
720
+ }
721
+
722
+ function validateVersionRange(value: string, label: string) {
723
+ if (validRange(value) == null) {
724
+ throw new ValidationError(
725
+ `Invalid value for label '${label}'. ` +
726
+ 'Expected a valid semver range; ' +
727
+ `got '${value}'`,
728
+ );
729
+ }
730
+ }
731
+
732
+ const contractRequirementLabelPrefix = 'io.balena.features.requires.';
733
+ const supportedContractRequirementLabels: Dict<ContractParser> = {
734
+ 'sw.supervisor': {
735
+ validate(value, label) {
736
+ validateVersionRange(value, label);
737
+ },
738
+ transform(value) {
739
+ return { type: 'sw.supervisor', version: value };
740
+ },
741
+ },
742
+ 'sw.l4t': {
743
+ validate(value, label) {
744
+ validateVersionRange(value, label);
745
+ },
746
+ transform(value) {
747
+ return { type: 'sw.l4t', version: value };
748
+ },
749
+ },
750
+ 'hw.device-type': {
751
+ validate() {
752
+ /* we might want to validate that the device type is a valid slug */
753
+ },
754
+ transform(value) {
755
+ return { type: 'hw.device-type', slug: value };
756
+ },
757
+ },
758
+ 'arch.sw': {
759
+ validate(value, label) {
760
+ if (!['aarch64', 'rpi', 'amd64', 'armv7hf', 'i386'].includes(value)) {
761
+ throw new ValidationError(
762
+ `Invalid value for label '${label}'. ` +
763
+ 'Expected a valid architecture string ' +
764
+ `got '${value}'`,
765
+ );
766
+ }
767
+ /* we might want to validate that the device type is a valid slug */
768
+ },
769
+ transform(value) {
770
+ return { type: 'arch.sw', slug: value };
771
+ },
772
+ },
773
+ };
774
+
775
+ /**
776
+ * Transforms a normalized composition into a list of image descriptors
777
+ * that can be used to pull or build a service image.
778
+ */
779
+ export function toImageDescriptors(c: Composition): ImageDescriptor[] {
780
+ return Object.entries(c.services).map(([name, service]) => {
781
+ return createImageDescriptor(name, service);
782
+ });
783
+ }
784
+
785
+ function createContractFromLabels(
786
+ serviceName: string,
787
+ labels?: Dict<string>,
788
+ ): ContractObject | null {
789
+ const requires = Object.entries(labels ?? {}).flatMap(([key, value]) => {
790
+ if (!key.startsWith(contractRequirementLabelPrefix)) {
791
+ return [];
792
+ }
793
+
794
+ key = key.replace(contractRequirementLabelPrefix, '');
795
+ if (!(key in supportedContractRequirementLabels)) {
796
+ return [];
797
+ }
798
+
799
+ const parser = supportedContractRequirementLabels[key];
800
+ return [parser.transform(value)];
801
+ });
802
+
803
+ if (requires.length === 0) {
804
+ return null;
805
+ }
806
+
807
+ return {
808
+ type: 'sw.container',
809
+ slug: `contract-for-${serviceName}`,
810
+ requires,
811
+ };
812
+ }
813
+
814
+ function createImageDescriptor(
815
+ serviceName: string,
816
+ service: Service,
817
+ ): ImageDescriptor {
818
+ const contract = createContractFromLabels(serviceName, service.labels);
819
+ if (service.image && !service.build) {
820
+ return {
821
+ serviceName,
822
+ image: service.image,
823
+ ...(contract && { contract }),
824
+ };
825
+ }
826
+ const build = service.build!;
827
+ return {
828
+ serviceName,
829
+ image: build,
830
+ ...(contract && { contract }),
831
+ };
832
+ }