__init__.py 43 KB
Newer Older
Rémi Duraffort's avatar
Rémi Duraffort committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# -*- coding: utf-8 -*-
# Copyright (C) 2017-2018 Linaro Limited
#
# Author: Neil Williams <neil.williams@linaro.org>
#         Senthil Kumaran <senthil.kumaran@linaro.org>
#
# This file is part of LAVA.
#
# LAVA is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License version 3
# as published by the Free Software Foundation
#
# LAVA is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with LAVA.  If not, see <http://www.gnu.org/licenses/>.

21
22
from functools import wraps
from simplejson import JSONDecodeError
23
import os
24
import sys
Neil Williams's avatar
Neil Williams committed
25
import xmlrpc.client
26
27
import yaml

28
from django.conf import settings
29
from django.core.exceptions import PermissionDenied
30
from django.db.models import Count, Q
31
from django.db import transaction
32
from linaro_django_xmlrpc.models import ExposedAPI
33
34
35
from lava_scheduler_app.models import (
    Device,
    DeviceType,
36
    JSONDataError,
37
    DevicesUnavailableException,
38
    TestJob,
Neil Williams's avatar
Neil Williams committed
39
)
40
from lava_scheduler_app.views import get_restricted_job
41
42
from lava_scheduler_app.dbutils import (
    device_type_summary,
43
44
    testjob_submission,
    active_device_types,
45
)
46
47
48
49
50
51
52
53
from lava_scheduler_app.schema import (
    validate_submission,
    validate_device,
    SubmissionException,
)

# functions need to be members to be exposed in the API
# pylint: disable=no-self-use
Michael-Doyle Hudson's avatar
Michael-Doyle Hudson committed
54

Neil Williams's avatar
Neil Williams committed
55
56
57
# to make a function visible in the API, it must be a member of SchedulerAPI
# pylint: disable=no-self-use

Michael-Doyle Hudson's avatar
Michael-Doyle Hudson committed
58

59
60
def check_perm(perm):
    """ decorator to check that the caller has the given permission """
61

62
63
64
65
66
67
68
    def decorator(f):
        @wraps(f)
        def wrapper(self, *args, **kwargs):
            self._authenticate()
            if not self.user.has_perm(perm):
                raise xmlrpc.client.Fault(
                    403,
69
                    "User '%s' is missing permission %s ." % (self.user.username, perm),
70
71
                )
            return f(self, *args, **kwargs)
72

73
        return wrapper
74

75
    return decorator
76
77


78
79
80
def build_device_status_display(state, health):
    if state == Device.STATE_IDLE:
        if health in [Device.HEALTH_GOOD, Device.HEALTH_UNKNOWN]:
81
            return "idle"
82
        elif health == Device.HEALTH_RETIRED:
83
            return "retired"
84
        else:
85
            return "offline"
86
    elif state == Device.STATE_RESERVED:
87
        return "reserved"
88
    else:
89
        return "running"
90
91


92
93
class SchedulerAPI(ExposedAPI):
    def submit_job(self, job_data):
94
95
96
97
98
99
100
        """
        Name
        ----
        `submit_job` (`job_data`)

        Description
        -----------
101
102
        Submit the given job data which is in LAVA job JSON or YAML format as a
        new job to LAVA scheduler.
103
104
105
106

        Arguments
        ---------
        `job_data`: string
107
            Job JSON or YAML string.
108
109
110
111

        Return value
        ------------
        This function returns an XML-RPC integer which is the newly created
112
        job's id, provided the user is authenticated with an username and token.
113
114
        If the job is a multinode job, this function returns the list of created
        job IDs.
115
        """
116
        self._authenticate()
Stevan Radakovic's avatar
Stevan Radakovic committed
117
        if not self.user.has_perm("lava_scheduler_app.submit_testjob"):
Neil Williams's avatar
Neil Williams committed
118
            raise xmlrpc.client.Fault(
119
120
                403,
                "Permission denied.  User %r does not have the "
Stevan Radakovic's avatar
Stevan Radakovic committed
121
                "'lava_scheduler_app.submit_testjob' permission.  Contact "
122
123
                "the administrators." % self.user.username,
            )
Neil Williams's avatar
Neil Williams committed
124
        try:
125
126
            job = testjob_submission(job_data, self.user)
        except SubmissionException as exc:
Neil Williams's avatar
Neil Williams committed
127
            raise xmlrpc.client.Fault(400, "Problem with submitted job data: %s" % exc)
Rémi Duraffort's avatar
Rémi Duraffort committed
128
        # FIXME: json error is not needed anymore
Neil Williams's avatar
Neil Williams committed
129
        except (JSONDataError, JSONDecodeError, ValueError) as exc:
Neil Williams's avatar
Neil Williams committed
130
            raise xmlrpc.client.Fault(400, "Decoding job submission failed: %s." % exc)
131
        except (Device.DoesNotExist, DeviceType.DoesNotExist):
Neil Williams's avatar
Neil Williams committed
132
            raise xmlrpc.client.Fault(404, "Specified device or device type not found.")
133
        except DevicesUnavailableException as exc:
Neil Williams's avatar
Neil Williams committed
134
            raise xmlrpc.client.Fault(400, "Device unavailable: %s" % str(exc))
135
        if isinstance(job, list):
136
            return [j.sub_id for j in job]
137
138
        else:
            return job.id
139

140
    def resubmit_job(self, job_id):
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
        """
        Name
        ----
        `resubmit_job` (`job_id`)

        Description
        -----------
        Resubmit the given job reffered by its id.

        Arguments
        ---------
        `job_id`: string
            The job's id which should be re-submitted.

        Return value
        ------------
        This function returns an XML-RPC integer which is the newly created
        job's id,  provided the user is authenticated with an username and
        token.
        """
161
        self._authenticate()
Stevan Radakovic's avatar
Stevan Radakovic committed
162
        if not self.user.has_perm("lava_scheduler_app.submit_testjob"):
Neil Williams's avatar
Neil Williams committed
163
            raise xmlrpc.client.Fault(
164
165
                403,
                "Permission denied.  User %r does not have the "
Stevan Radakovic's avatar
Stevan Radakovic committed
166
                "'lava_scheduler_app.submit_testjob' permission.  Contact "
167
168
                "the administrators." % self.user.username,
            )
Paul Larson's avatar
Paul Larson committed
169
        try:
170
            job = get_restricted_job(self.user, job_id)
Paul Larson's avatar
Paul Larson committed
171
        except TestJob.DoesNotExist:
Neil Williams's avatar
Neil Williams committed
172
            raise xmlrpc.client.Fault(404, "Specified job not found.")
173

174
        if job.is_multinode:
175
176
177
            return self.submit_job(job.multinode_definition)
        else:
            return self.submit_job(job.definition)
178

179
    def cancel_job(self, job_id):
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
        """
        Name
        ----
        `cancel_job` (`job_id`)

        Description
        -----------
        Cancel the given job reffered by its id.

        Arguments
        ---------
        `job_id`: string
            Job id which should be canceled.

        Return value
        ------------
        None. The user should be authenticated with an username and token.
        """
198
199
        self._authenticate()
        if not job_id:
200
            raise xmlrpc.client.Fault(400, "Bad request: TestJob id was not specified.")
201

202
203
204
205
        with transaction.atomic():
            try:
                job = get_restricted_job(self.user, job_id, for_update=True)
            except PermissionDenied:
Neil Williams's avatar
Neil Williams committed
206
                raise xmlrpc.client.Fault(
207
208
                    401, "Permission denied for user to job %s" % job_id
                )
209
            except TestJob.DoesNotExist:
Neil Williams's avatar
Neil Williams committed
210
                raise xmlrpc.client.Fault(404, "Specified job not found.")
211
212
213
214
215

            if job.state in [TestJob.STATE_CANCELING, TestJob.STATE_FINISHED]:
                # Don't do anything for jobs that ended already
                return True
            if not job.can_cancel(self.user):
Neil Williams's avatar
Neil Williams committed
216
                raise xmlrpc.client.Fault(403, "Permission denied.")
217
218
219

            if job.is_multinode:
                multinode_jobs = TestJob.objects.select_for_update().filter(
220
221
                    target_group=job.target_group
                )
222
223
224
225
226
227
                for multinode_job in multinode_jobs:
                    multinode_job.go_state_canceling()
                    multinode_job.save()
            else:
                job.go_state_canceling()
                job.save()
228
        return True
229

230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
    def validate_yaml(self, yaml_string):
        """
        Name
        ----
        validate_yaml (yaml_job_data)

        Description
        -----------
        Validate the supplied pipeline YAML against the submission schema.

        Note: this does not validate the job itself, just the YAML against the
        submission schema. A job which validates against the schema can still be
        an invalid job for the dispatcher and such jobs will be accepted as Submitted,
        scheduled and then marked as Incomplete with a failure comment. Full validation
        only happens after a device has been assigned to the Submitted job.

        Arguments
        ---------
        'yaml_job_data': string

        Return value
        ------------
        Raises an Exception if the yaml_job_data is invalid.
        """
        try:
            # YAML can parse JSON as YAML, JSON cannot parse YAML at all
256
            yaml_data = yaml.safe_load(yaml_string)
257
        except yaml.YAMLError as exc:
Neil Williams's avatar
Neil Williams committed
258
            raise xmlrpc.client.Fault(400, "Decoding job submission failed: %s." % exc)
259
260
261
262
        try:
            # validate against the submission schema.
            validate_submission(yaml_data)  # raises SubmissionException if invalid.
        except SubmissionException as exc:
Neil Williams's avatar
Neil Williams committed
263
            raise xmlrpc.client.Fault(400, "Invalid YAML submission: %s" % exc)
264

265
    def job_output(self, job_id, offset=0):
266
267
268
        """
        Name
        ----
269
        `job_output` (`job_id`, `offset=0`)
270
271
272
273
274
275
276
277
278

        Description
        -----------
        Get the output of given job id.

        Arguments
        ---------
        `job_id`: string
            Job id for which the output is required.
279
280
281
        `offset`: integer
            Offset from which to start reading the output file specified in bytes.
            It defaults to 0.
282
283
284

        Return value
        ------------
285
286
        This function returns an XML-RPC binary data of output file, provided
        the user is authenticated with an username and token.
287
        """
288
289
        self._authenticate()
        if not job_id:
290
            raise xmlrpc.client.Fault(400, "Bad request: TestJob id was not specified.")
291
        try:
292
            job = get_restricted_job(self.user, job_id)
293
        except PermissionDenied:
Neil Williams's avatar
Neil Williams committed
294
            raise xmlrpc.client.Fault(
295
296
                401, "Permission denied for user to job %s" % job_id
            )
297
        except TestJob.DoesNotExist:
Neil Williams's avatar
Neil Williams committed
298
            raise xmlrpc.client.Fault(404, "Specified job not found.")
299

300
301
302
303
304
305
306
307
        # Open the logs
        output_path = os.path.join(job.output_dir, "output.yaml")
        try:
            with open(output_path, encoding="utf-8", errors="replace") as f_logs:
                if f_logs:
                    f_logs.seek(offset)
                return xmlrpc.client.Binary(f_logs.read().encode("UTF-8"))
        except OSError:
Neil Williams's avatar
Neil Williams committed
308
            raise xmlrpc.client.Fault(404, "Job output not found.")
309
310
311
312
313
314
315
316
317

    def all_devices(self):
        """
        Name
        ----
        `all_devices` ()

        Description
        -----------
318
        Get all the available devices with their state and type information.
319
320
321
322
323
324
325
326

        Arguments
        ---------
        None

        Return value
        ------------
        This function returns an XML-RPC array in which each item is a list of
327
328
        device hostname, device type, device state, current running job id and
        if device is pipeline. For example:
329

330
        [['panda01', 'panda', 'running', 'good', 164, False], ['qemu01', 'qemu', 'idle', 'unknwon', None, True]]
331
332
        """

Stevan Radakovic's avatar
Stevan Radakovic committed
333
334
335
        devices_list = Device.objects.visible_by_user(self.user).exclude(
            health=Device.HEALTH_RETIRED
        )
336

337
338
339
340
341
342
343
344
345
346
        return [
            [
                dev.hostname,
                dev.device_type.name,
                build_device_status_display(dev.state, dev.health),
                dev.current_job().pk if dev.current_job() else None,
                True,
            ]
            for dev in devices_list
        ]
347
348
349
350
351
352
353
354
355
356

    def all_device_types(self):
        """
        Name
        ----
        `all_device_types` ()

        Description
        -----------
        Get all the available device types with their state and count
357
        information.
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372

        Arguments
        ---------
        None

        Return value
        ------------
        This function returns an XML-RPC array in which each item is a dict
        which contains name (device type), idle, busy, offline counts.
        For example:

        [{'idle': 1, 'busy': 0, 'name': 'panda', 'offline': 0},
        {'idle': 1, 'busy': 0, 'name': 'qemu', 'offline': 0}]
        """

373
        all_device_types = []
374
        keys = ["busy", "idle", "offline"]
375

Stevan Radakovic's avatar
Stevan Radakovic committed
376
        device_types = device_type_summary(self.user)
377
378

        for dev_type in device_types:
379
            device_type = {"name": dev_type["device_type"]}
380
            for key in keys:
Neil Williams's avatar
Neil Williams committed
381
                device_type[key] = dev_type[key]
382
            all_device_types.append(device_type)
383

384
        return all_device_types
385

386
387
388
    def get_recent_jobs_for_device_type(
        self, device_type, count=1, restrict_to_user=False
    ):
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
        """
        Name
        ----

        `get_recent_jobs_for_device_type` (`device_type`, `count=1`, `restrict_to_user=False`)

        Description
        -----------
        Get details of recently finished jobs for a given device_type. Limits the list
        to test jobs submitted by the user making the query if restrict_to_user is set to
        True. Get only the most recent job by default, but count can be set higher to
        get for example the last 10 jobs.

        Arguments
        ---------
        `device_type`: string
            Name of the device_type for which you want the jobs
        `count`: integer (Optional, default=1)
            Number of last jobs you want
        `restrict_to_user`: boolean (Optional, default=False)
            Fetch only the jobs submitted by the user making the query if set to True

        Return value
        ------------
        This function returns a list of dictionaries, which correspond to the
        list of recently finished jobs informations (Complete or Incomplete)
        for this device, ordered from youngest to oldest.

        [
            {
                'description': 'ramdisk health check',
                'id': 359828,
                'status': 'Complete',
                'device': 'black01'
            },
            {
                'description': 'standard ARMMP NFS',
                'id': 359827
                'status': 'Incomplete',
                'device': 'black02'
            }
        ]
        """
        if not device_type:
Neil Williams's avatar
Neil Williams committed
433
            raise xmlrpc.client.Fault(
434
435
436
                400, "Bad request: device_type was not specified."
            )
        if count < 0:
437
            raise xmlrpc.client.Fault(400, "Bad request: count must not be negative.")
438
439
440
        try:
            dt = DeviceType.objects.get(name=device_type, display=True)
        except Device.DoesNotExist:
Neil Williams's avatar
Neil Williams committed
441
            raise xmlrpc.client.Fault(
442
443
444
                404, "DeviceType '%s' was not found." % device_type
            )

445
446
447
        job_qs = (
            TestJob.objects.filter(state=TestJob.STATE_FINISHED)
            .filter(requested_device_type=dt)
Stevan Radakovic's avatar
Stevan Radakovic committed
448
            .visible_by_user(self.user)
449
450
            .order_by("-id")
        )
451
452
453
454
        if restrict_to_user:
            job_qs = job_qs.filter(submitter=self.user)
        job_list = []
        for job in job_qs.all()[:count]:
455
            hostname = ""
456
457
            if job.actual_device:
                hostname = job.actual_device.hostname
458
459
460
            job_dict = {
                "id": job.id,
                "description": job.description,
Rémi Duraffort's avatar
Rémi Duraffort committed
461
                "status": job.get_legacy_status_display(),
462
                "device": hostname,
463
464
465
466
            }
            job_list.append(job_dict)
        return job_list

467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
    def get_recent_jobs_for_device(self, device, count=1, restrict_to_user=False):
        """
        Name
        ----

        `get_recent_jobs_for_device` (`device`, `count=1`, `restrict_to_user=False`)

        Description
        -----------
        Get details of recently finished jobs for a given device. Limits the list
        to test jobs submitted by the user making the query if restrict_to_user is set to
        True. Get only the most recent job by default, but count can be set higher to
        get for example the last 10 jobs.

        Arguments
        ---------
        `device`: string
            Name of the device for which you want the jobs
        `count`: integer (Optional, default=1)
            Number of last jobs you want
        `restrict_to_user`: boolean (Optional, default=False)
            Fetch only the jobs submitted by the user making the query if set to True

        Return value
        ------------
        This function returns a list of dictionaries, which correspond to the
        list of recently finished jobs informations (Complete or Incomplete)
        for this device, ordered from youngest to oldest.

        [
            {
                'description': 'mainline--armada-370-db--multi_v7_defconfig--network',
                'id': 359828,
                'status': 'Complete'
            },
            {
                'description': 'mainline--armada-370-db--multi_v7_defconfig--sata',
                'id': 359827
                'status': 'Incomplete'
            }
        ]
        """
        if not device:
510
            raise xmlrpc.client.Fault(400, "Bad request: device was not specified.")
511
        if count < 0:
512
            raise xmlrpc.client.Fault(400, "Bad request: count must not be negative.")
513
514
515
        try:
            device_obj = Device.objects.get(hostname=device)
        except Device.DoesNotExist:
516
            raise xmlrpc.client.Fault(404, "Device '%s' was not found." % device)
517

Stevan Radakovic's avatar
Stevan Radakovic committed
518
        if not device_obj.can_view(self.user):
Neil Williams's avatar
Neil Williams committed
519
            raise xmlrpc.client.Fault(
520
                403, "Device '%s' not available to user '%s'." % (device, self.user)
521
            )
522
523
524
        job_qs = (
            TestJob.objects.filter(state=TestJob.STATE_FINISHED)
            .filter(actual_device=device_obj)
Stevan Radakovic's avatar
Stevan Radakovic committed
525
            .visible_by_user(self.user)
526
527
            .order_by("-id")
        )
528
529
530
531
532
533
534
        if restrict_to_user:
            job_qs = job_qs.filter(submitter=self.user)
        job_list = []
        for job in job_qs.all()[:count]:
            job_dict = {
                "id": job.id,
                "description": job.description,
Rémi Duraffort's avatar
Rémi Duraffort committed
535
                "status": job.get_legacy_status_display(),
536
537
538
539
            }
            job_list.append(job_dict)
        return job_list

540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
    def get_device_type_by_alias(self, alias):
        """
        Name
        ----

        `get_device_type_by_alias` (`alias`)

        Description
        -----------
        Get the matching device-type(s) for the specified alias. It is
        possible that more than one device-type can be returned, depending
        on local admin configuration. An alias can be used to provide the
        link between the device-type name and the Device Tree name.
        It is possible for multiple device-types to have the same alias
        (to assist in transitions and migrations).
        The specified alias string can be a partial match, returning all
        device-types which have an alias name containing the requested
        string.

        Arguments
        ---------
        `alias`: string
            Name of the alias to lookup

        Return value
        ------------
        This function returns a dictionary containing the alias as the key
        and a list of device-types which use that alias as the value. If the
        specified alias does not match any device-type, the dictionary contains
        an empty list for the alias key.

        {'apq8016-sbc': ['dragonboard410c']}
        {'ompa4-panda': ['panda', 'panda-es']}
        """

Stevan Radakovic's avatar
Stevan Radakovic committed
575
576
577
        aliases = DeviceType.objects.filter(
            aliases__name__contains=alias
        ).visible_by_user(self.user)
578
        return {alias: [device_type.name for device_type in aliases]}
579

580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
    def get_device_status(self, hostname):
        """
        Name
        ----
        `get_device_status` (`hostname`)

        Description
        -----------
        Get status, running job, date from which it is offline of the given
        device and the user who put it offline.

        Arguments
        ---------
        `hostname`: string
            Name of the device for which the status is asked.

        Return value
        ------------
        This function returns an XML-RPC dictionary which contains hostname,
        status, date from which the device is offline if the device is offline,
        the user who put the device offline if the device is offline and the
        job id of the running job.
        The device has to be visible to the user who requested device's status.

        Note that offline_since and offline_by can be empty strings if the device
        status is manually changed by an administrator in the database or from
        the admin site of LAVA even if device's status is offline.
        """

        if not hostname:
610
            raise xmlrpc.client.Fault(400, "Bad request: Hostname was not specified.")
611
612
613
        try:
            device = Device.objects.get(hostname=hostname)
        except Device.DoesNotExist:
614
            raise xmlrpc.client.Fault(404, "Device '%s' was not found." % hostname)
615
616

        device_dict = {}
Stevan Radakovic's avatar
Stevan Radakovic committed
617
        if device.can_view(self.user):
618
            device_dict["hostname"] = device.hostname
619
620
621
            device_dict["status"] = build_device_status_display(
                device.state, device.health
            )
622
623
624
            device_dict["job"] = None
            device_dict["offline_since"] = None
            device_dict["offline_by"] = None
Rémi Duraffort's avatar
Rémi Duraffort committed
625
            device_dict["is_pipeline"] = True
626

627
628
629
            current_job = device.current_job()
            if current_job is not None:
                device_dict["job"] = current_job.pk
630
        else:
Neil Williams's avatar
Neil Williams committed
631
            raise xmlrpc.client.Fault(
632
633
634
635
                403, "Permission denied for user to access %s information." % hostname
            )
        return device_dict

636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
    def put_into_maintenance_mode(self, hostname, reason, notify=None):
        """
        Name
        ----
        `put_into_maintenance_mode` (`hostname`, `reason`, `notify`)

        Description
        -----------
        Put the given device in maintenance mode with the given reason and optionally
        notify the given mail address when the job has finished.

        Arguments
        ---------
        `hostname`: string
            Name of the device to put into maintenance mode.
        `reason`: string
            The reason given to justify putting the device into maintenance mode.
        `notify`: string
            Email address of the user to notify when the job has finished. Can be
            omitted.

        Return value
        ------------
        None. The user should be authenticated with a username and token and has
        sufficient permission.
        """

        self._authenticate()
        if not hostname:
665
            raise xmlrpc.client.Fault(400, "Bad request: Hostname was not specified.")
666
        if not reason:
667
            raise xmlrpc.client.Fault(400, "Bad request: Reason was not specified.")
668
669
670
671
        with transaction.atomic():
            try:
                device = Device.objects.select_for_update().get(hostname=hostname)
            except Device.DoesNotExist:
672
                raise xmlrpc.client.Fault(404, "Device '%s' was not found." % hostname)
673
674
675
676
            if device.can_admin(self.user):
                device.health = Device.HEALTH_MAINTENANCE
                device.save()
            else:
Neil Williams's avatar
Neil Williams committed
677
                raise xmlrpc.client.Fault(
678
679
680
                    403,
                    "Permission denied for user to put %s into maintenance mode."
                    % hostname,
681
                )
682

683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
    def put_into_online_mode(self, hostname, reason, skip_health_check=False):
        """
        Name
        ----
        `put_into_online_mode` (`hostname`, `reason`, `skip_health_check`)

        Description
        -----------
        Put the given device into online mode with the given reason ans skip health
        check if asked.

        Arguments
        ---------
        `hostname`: string
            Name of the device to put into online mode.
        `reason`: string
            The reason given to justify putting the device into online mode.
        `skip_health_check`: boolean
            Skip health check when putting the board into online mode. If
            omitted, health check is not skipped by default.

        Return value
        ------------
        None. The user should be authenticated with a username and token and has
        sufficient permission.
        """

        self._authenticate()
        if not hostname:
712
            raise xmlrpc.client.Fault(400, "Bad request: Hostname was not specified.")
713
        if not reason:
714
            raise xmlrpc.client.Fault(400, "Bad request: Reason was not specified.")
715
716
717
718
        with transaction.atomic():
            try:
                device = Device.objects.select_for_update().get(hostname=hostname)
            except Device.DoesNotExist:
719
                raise xmlrpc.client.Fault(404, "Device '%s' was not found." % hostname)
720
721
722
723
            if device.can_admin(self.user):
                device.health = Device.HEALTH_UNKNOWN
                device.save()
            else:
Neil Williams's avatar
Neil Williams committed
724
                raise xmlrpc.client.Fault(
725
726
                    403,
                    "Permission denied for user to put %s into online mode." % hostname,
727
                )
728

729
    def pending_jobs_by_device_type(self, all=False):
730
731
732
        """
        Name
        ----
733
        `pending_jobs_by_device_type` ()
734
735
736

        Description
        -----------
737
        Get number of pending jobs in each device type.
738
739
        Private test jobs and hidden device types are
        excluded, except for authenticated superusers.
740
741
742

        Arguments
        ---------
743
        `all`: boolean - include retired devices and undisplayed device-types in the listing.
744
745
746

        Return value
        ------------
747
748
        This function returns a dict where the key is the device type and
        the value is the number of jobs pending in that device type.
749
750
        For example:

751
        {'qemu': 0, 'panda': 3}
752
753
        """

754
        pending_jobs_by_device = {}
755

Stevan Radakovic's avatar
Stevan Radakovic committed
756
757
758
        jobs_res = TestJob.objects.filter(
            state=TestJob.STATE_SUBMITTED
        ).visible_by_user(self.user)
759
        jobs_res = jobs_res.exclude(requested_device_type_id__isnull=True)
760
761
        jobs_res = jobs_res.values_list("requested_device_type_id")
        jobs_res = jobs_res.annotate(pending_jobs=(Count("id")))
762

763
764
765
        jobs = {}
        jobs_hash = dict(jobs_res)
        for job in jobs_hash:
766
            jobs[job] = jobs_hash[job]
767
        pending_jobs_by_device.update(jobs)
768

769
        # Get rest of the devices and put number of pending jobs as 0.
770
        if all:
771
            device_types = DeviceType.objects.all()
772
        else:
773
            device_types = active_device_types()
774

Stevan Radakovic's avatar
Stevan Radakovic committed
775
        device_types = device_types.visible_by_user(self.user)
776
        for device_type in device_types.values_list("name", flat=True):
777
778
            if device_type not in pending_jobs_by_device:
                pending_jobs_by_device[device_type] = 0
Neil Williams's avatar
Neil Williams committed
779

780
        return pending_jobs_by_device
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800

    def job_details(self, job_id):
        """
        Name
        ----
        `job_details` (`job_id`)

        Description
        -----------
        Get the details of given job id.

        Arguments
        ---------
        `job_id`: string
            Job id for which the output is required.

        Return value
        ------------
        This function returns an XML-RPC structures of job details, provided
        the user is authenticated with an username and token.
801
802

        The elements available in XML-RPC structure include:
Rémi Duraffort's avatar
Rémi Duraffort committed
803
        _state, submitter_id, is_pipeline, id, failure_comment,
Stevan Radakovic's avatar
Stevan Radakovic committed
804
        multinode_definition, priority, _actual_device_cache,
805
        original_definition, status, health_check, description,
Stevan Radakovic's avatar
Stevan Radakovic committed
806
807
808
        start_time, target_group, pipeline_compatibility, submit_time,
        is_public, _old_status, actual_device_id, definition, sub_id,
        requested_device_type_id, end_time, absolute_url, submitter_username
809
        """
810
        self._authenticate()
811
        if not job_id:
812
            raise xmlrpc.client.Fault(400, "Bad request: TestJob id was not specified.")
813
        try:
814
            job = get_restricted_job(self.user, job_id)
Rémi Duraffort's avatar
Rémi Duraffort committed
815
            job.status = job.get_legacy_status_display()
816
817
            job.state = job.get_state_display()
            job.health = job.get_health_display()
818
            job.submitter_username = job.submitter.username
819
            job.absolute_url = job.get_absolute_url()
Rémi Duraffort's avatar
Rémi Duraffort committed
820
            job.is_pipeline = True
821
        except PermissionDenied:
Neil Williams's avatar
Neil Williams committed
822
            raise xmlrpc.client.Fault(
823
824
                401, "Permission denied for user to job %s" % job_id
            )
825
        except TestJob.DoesNotExist:
Neil Williams's avatar
Neil Williams committed
826
            raise xmlrpc.client.Fault(404, "Specified job not found.")
827
828

        return job
829
830
831
832
833

    def job_status(self, job_id):
        """
        Name
        ----
834
835
        DEPRECATED - use `job_health` or `job_state` instead.

836
        `job_status` (`job_id`)
837
838
839
840
841
842
843
844
845
846
847
848

        Description
        -----------
        Get the status of given job id.

        Arguments
        ---------
        `job_id`: string
            Job id for which the output is required.

        Return value
        ------------
849
850
        This function returns an XML-RPC structures of job status with the
        following fields.
851
        The user is authenticated with an username and token.
Neil Williams's avatar
Neil Williams committed
852

853
        `job_status`: string
854
        ['Submitted'|'Running'|'Complete'|'Incomplete'|'Canceled'|'Canceling']
855
856

        `bundle_sha1`: string
857
        The sha1 hash code of the bundle, if it existed. Otherwise it will be
858
        an empty string. (LAVA V1 only)
859
        """
860
861
        self._authenticate()
        if not job_id:
862
            raise xmlrpc.client.Fault(400, "Bad request: TestJob id was not specified.")
863
        try:
864
            job = get_restricted_job(self.user, job_id)
865
        except PermissionDenied:
Neil Williams's avatar
Neil Williams committed
866
            raise xmlrpc.client.Fault(
867
868
                401, "Permission denied for user to job %s" % job_id
            )
869
        except TestJob.DoesNotExist:
Neil Williams's avatar
Neil Williams committed
870
            raise xmlrpc.client.Fault(404, "Specified job not found.")
871

872
        job_status = {"job_id": job.id}
873
874

        if job.is_multinode:
875
876
877
878
879
            job_status.update({"sub_id": job.sub_id})

        job_status.update(
            {"job_status": job.get_legacy_status_display(), "bundle_sha1": ""}
        )
880
        return job_status
881

882
883
884
885
    def job_list_status(self, job_id_list):
        """
        Name
        ----
886
887
        DEPRECATED - use `job_health` or `job_state` instead.

888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
        job_list_status ([job_id, job_id, job_id])

        Description
        -----------
        Get the status of a list of job ids.

        Arguments
        ---------
        `job_id_list`: list
            List of job ids for which the output is required.
            For multinode jobs specify the job sub_id as a float
            in the XML-RPC call:
            job_list_status([1, 2, 3,1, 5])

        Return value
        ------------
        The user needs to be authenticated with an username and token.

        This function returns an XML-RPC structure of job status with the
        following content.

        `job_status`: string
        {ID: ['Submitted'|'Running'|'Complete'|'Incomplete'|'Canceled'|'Canceling']}

        If the user is not able to view one of the specified jobs, that entry
        will be omitted.

        """
        self._authenticate()
        job_status = {}
        # optimise the query for a long list instead of using the
        # convenience handlers
        if not isinstance(job_id_list, list):
Neil Williams's avatar
Neil Williams committed
921
            raise xmlrpc.client.Fault(400, "Bad request: needs to be a list")
922
        if not all(isinstance(chk, (float, int)) for chk in job_id_list):
923
924
925
            raise xmlrpc.client.Fault(
                400, "Bad request: needs to be a list of integers or floats"
            )
Stevan Radakovic's avatar
Stevan Radakovic committed
926
927
928
929
930
        jobs = (
            TestJob.objects.filter(Q(id__in=job_id_list) | Q(sub_id__in=job_id_list))
            .visible_by_user(self.user)
            .select_related("actual_device", "requested_device_type")
        )
931
        for job in jobs:
Rémi Duraffort's avatar
Rémi Duraffort committed
932
            job_status[str(job.display_id)] = job.get_legacy_status_display()
933
934
        return job_status

935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
    def job_health(self, job_id):
        """
        Name
        ----
        `job_health` (`job_id`)

        Description
        -----------
        Get the health of given job id.

        Arguments
        ---------
        `job_id`: string
            Job id for which the output is required.

        Return value
        ------------
        This function returns an XML-RPC structures of job health with the
        following fields.
        The user is authenticated with an username and token.

        `job_health`: string
        ['Unknown'|'Complete'|'Incomplete'|'Canceled']
        """
        self._authenticate()
        if not job_id:
961
            raise xmlrpc.client.Fault(400, "Bad request: TestJob id was not specified.")
962
963
964
        try:
            job = get_restricted_job(self.user, job_id)
        except PermissionDenied:
Neil Williams's avatar
Neil Williams committed
965
            raise xmlrpc.client.Fault(
966
967
                401, "Permission denied for user to job %s" % job_id
            )
968
        except TestJob.DoesNotExist:
Neil Williams's avatar
Neil Williams committed
969
            raise xmlrpc.client.Fault(404, "Specified job not found.")
970

971
        job_health = {"job_id": job.id, "job_health": job.get_health_display()}
972
973

        if job.is_multinode:
974
            job_health.update({"sub_id": job.sub_id})
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003

        return job_health

    def job_state(self, job_id):
        """
        Name
        ----
        `job_state` (`job_id`)

        Description
        -----------
        Get the state of given job id.

        Arguments
        ---------
        `job_id`: string
            Job id for which the output is required.

        Return value
        ------------
        This function returns an XML-RPC structures of job state with the
        following fields.
        The user is authenticated with an username and token.

        `job_state`: string
        ['Submitted'|'Scheduling'|'Scheduled'|'Running'|'Canceling'|'Finished']
        """
        self._authenticate()
        if not job_id:
1004
            raise xmlrpc.client.Fault(400, "Bad request: TestJob id was not specified.")
1005
1006
1007
        try:
            job = get_restricted_job(self.user, job_id)
        except PermissionDenied:
Neil Williams's avatar
Neil Williams committed
1008
            raise xmlrpc.client.Fault(
1009
1010
                401, "Permission denied for user to job %s" % job_id
            )
1011
        except TestJob.DoesNotExist:
Neil Williams's avatar
Neil Williams committed
1012
            raise xmlrpc.client.Fault(404, "Specified job not found.")
1013

1014
        job_state = {"job_id": job.id, "job_state": job.get_state_display()}
1015
1016

        if job.is_multinode:
1017
            job_state.update({"sub_id": job.sub_id})
1018
1019
1020

        return job_state

1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
    def all_jobs(self):
        """
        Name
        ----
        `all_jobs` ()

        Description
        -----------
        Get submitted or running jobs.

        Arguments
        ---------
        None

        Return value
        ------------
        This function returns a XML-RPC array of submitted and running jobs with their status and
        actual device for running jobs and requested device or device type for submitted jobs and
        job sub_id for multinode jobs.
        For example:

1042
1043
1044
        [[73, 'multinode-job', 'submitted', None, 'kvm', '72.1'],
        [72, 'multinode-job', 'submitted', None, 'kvm', '72.0'],
        [71, 'test-job', 'running', 'kvm01', None, None]]
1045
1046
        """

Stevan Radakovic's avatar
Stevan Radakovic committed
1047
1048
1049
1050
1051
        jobs = (
            TestJob.objects.exclude(state=TestJob.STATE_FINISHED)
            .visible_by_user(self.user)
            .order_by("-id")
        )
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
        jobs_list = [
            [
                job.id,
                job.description,
                job.get_legacy_status_display().lower(),
                job.actual_device,
                job.requested_device_type,
                job.sub_id,
            ]
            for job in jobs
        ]
1063
1064

        return jobs_list
1065
1066
1067
1068
1069

    def get_pipeline_device_config(self, device_hostname):
        """
        Name
        ----
1070
1071
        DEPRECATED - use `get_device_config` instead.

1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
        `get_pipeline_device_config` (`device_hostname`)

        Description
        -----------
        Get the pipeline device configuration for given device hostname.

        Arguments
        ---------
        `device_hostname`: string
            Device hostname for which the configuration is required.

1083
1084
1085
1086
        Return value
        ------------
        This function returns an XML-RPC binary data of output file.
        """
1087
        return self.get_device_config(device_hostname)
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110

    def get_device_config(self, device_hostname, context=None):
        """
        New in api_version 2 - see system.api_version()

        Name
        ----
        `get_device_config` (`device_hostname`, context=None)

        Description
        -----------
        Get the device configuration for given device hostname.

        Arguments
        ---------
        `device_hostname`: string
            Device hostname for which the configuration is required.

        Some device templates need a context specified when processing the
        device-type template. This can be specified as a YAML string:

        `get_device_config` `('qemu01', '{arch: amd64}')`

1111
1112
1113
1114
1115
        Return value
        ------------
        This function returns an XML-RPC binary data of output file.
        """
        if not device_hostname:
Neil Williams's avatar
Neil Williams committed
1116
            raise xmlrpc.client.Fault(
1117
1118
                400, "Bad request: Device hostname was not specified."
            )
1119

1120
1121
1122
        job_ctx = None
        if context is not None:
            try:
1123
                job_ctx = yaml.safe_load(context)
1124
            except yaml.YAMLError as exc:
Neil Williams's avatar
Neil Williams committed
1125
                raise xmlrpc.client.Fault(
1126
1127
                    400, "Job context '%s' is not valid. %s" % (context, exc)
                )
1128
1129
1130
        try:
            device = Device.objects.get(hostname=device_hostname)
        except Device.DoesNotExist:
Neil Williams's avatar
Neil Williams committed
1131
            raise xmlrpc.client.Fault(404, "Specified device was not found.")
1132

Stevan Radakovic's avatar
Stevan Radakovic committed
1133
1134
1135
1136
1137
        if not device.can_view(self.user):
            raise xmlrpc.client.Fault(
                401, "Permission denied for user to device %s" % device.hostname
            )

1138
        config = device.load_configuration(job_ctx=job_ctx, output_format="yaml")
1139
1140

        # validate against the device schema
1141
        validate_device(yaml.safe_load(config))
1142

1143
        return xmlrpc.client.Binary(config.encode("UTF-8"))
1144
1145
1146
1147
1148
1149
1150
1151
1152

    def import_device_dictionary(self, hostname, jinja_str):
        """
        Name
        ----
        `import_device_dictionary` (`device_hostname`, `jinja_string`)

        Description
        -----------
Stevan Radakovic's avatar
Stevan Radakovic committed
1153
        [user with admin_device permission only]
1154
1155
1156
1157
1158
1159
1160
1161
        Import or update the device dictionary key value store for a
        pipeline device.

        Arguments
        ---------
        `device_hostname`: string
            Device hostname to update.
        `jinja_str`: string
1162
            Device configuration as Jinja2
1163
1164
1165
1166
1167
1168
1169

        Return value
        ------------
        This function returns an XML-RPC binary data of output file.
        """
        self._authenticate()
        try:
1170
            device = Device.objects.get(hostname=hostname)
1171
        except DeviceType.DoesNotExist:
1172
            raise xmlrpc.client.Fault(404, "Device '%s' was not found." % hostname)
Stevan Radakovic's avatar
Stevan Radakovic committed
1173
1174
1175
1176
1177
1178
        if device.can_admin(self.user):
            if not device.save_configuration(jinja_str):
                raise xmlrpc.client.Fault(
                    400, "Unable to store the configuration for %s on disk" % hostname
                )
        else:
Neil Williams's avatar
Neil Williams committed
1179
            raise xmlrpc.client.Fault(
1180
1181
1182
                403,
                "Permission denied for user to store the configuration for %s on disk."
                % hostname,
1183
            )
1184
1185

        return "Device dictionary updated for %s" % hostname
1186
1187
1188
1189
1190
1191
1192
1193
1194

    def export_device_dictionary(self, hostname):
        """
        Name
        ----
        `export_device_dictionary` (`device_hostname`)

        Description
        -----------
Stevan Radakovic's avatar
Stevan Radakovic committed
1195
        [user with admin permission only]
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
        Export the device dictionary key value store for a
        pipeline device.

        See also get_pipeline_device_config

        Arguments
        ---------
        `device_hostname`: string
            Device hostname to update.

        Return value
        ------------
        This function returns an XML-RPC binary data of output file.
        """
        self._authenticate()
        try:
            device = Device.objects.get(hostname=hostname)
        except DeviceType.DoesNotExist:
1214
            raise xmlrpc.client.Fault(404, "Device '%s' was not found." % hostname)
Stevan Radakovic's avatar
Stevan Radakovic committed
1215
1216
1217
1218
1219
1220
1221
        if device.can_admin(self.user):
            device_dict = device.load_configuration(output_format="raw")
            if not device_dict:
                raise xmlrpc.client.Fault(
                    404, "Device '%s' does not have a device dictionary" % hostname
                )
        else:
Neil Williams's avatar
Neil Williams committed
1222
            raise xmlrpc.client.Fault(
1223
1224
1225
                403,
                "Permission denied for user to retrieve device dictionary for '%s'."
                % hostname,
1226
            )
1227

1228
        return xmlrpc.client.Binary(device_dict.encode("UTF-8"))
1229

1230
    def validate_pipeline_devices(self, name=None):
1231
1232
1233
        """
        Name
        ----
1234
        `validate_pipeline_device` [`name`]
1235
1236
1237
1238
1239
1240

        Description
        -----------
        Validate that the device dictionary and device-type template
        together create a valid YAML file which matches the pipeline
        device schema.
1241
        Retired devices are ignored.
1242
1243
1244
1245
1246

        See also get_pipeline_device_config

        Arguments
        ---------
1247
1248
1249
1250
1251
1252
1253