| | 600 | |
| | 601 | === Libraries === |
| | 602 | |
| | 603 | Libraries are groups of experiments used to collect related experiments. For example, a testbed may have a library of experiments for new users to realize and study in learning to use the testbed. A research group might collect a set of regression tests into a library. |
| | 604 | |
| | 605 | As with experiments, access to the library is controlled by circles. A library if beginner experiments might be readable by the world circle while a specific research group would protect their libraries using project circles or smaller. |
| | 606 | |
| | 607 | Libraries also have [wiki:SPIDocs#Profiles profiles] attached to them so that other users can understand the purpose and goals of the library. |
| | 608 | |
| | 609 | |
| | 610 | ==== Library Names ==== |
| | 611 | |
| | 612 | Every circle has a unique ''libraryid'' that names it in the testbed. Library names are scoped by either userids or projectids. A libraryid has the form of either: |
| | 613 | |
| | 614 | * userid:local_name |
| | 615 | * projectid:local_name |
| | 616 | |
| | 617 | So there may be libraries named `some_user:experiments` and `some_project:experiments`. They are distinct. |
| | 618 | |
| | 619 | That scoping serves 2 purposes: disambiguating common names and providing a way to distinguish certain names. We expect that many users will set up libraries with local names like `test`, `development`, `paper_results` and the like. The user interfaces built on the SPI can scope such names by the userid creating them and hide the prefix unless it is necessary to disambiguate. |
| | 620 | |
| | 621 | When a user creates a name in scoped by a project name, it is functionally equivalent to a userid-scoped name, but applications may choose to distinguish them. One can easily imagine that `some_user:development` and `some_project:development` refer to different sets of experiments and that the project-prefixed library is administered more carefully and used more widely. |
| | 622 | The right to create a library in a project's name space - prefixed by the projectid - is controlled by [wiki:SPIDocs#ProjectPermissions project permissions]. |
| | 623 | |
| | 624 | ==== Library Permissions ==== |
| | 625 | |
| | 626 | As with other abstractions, access to libraries is controlled by permissions. These permissions are assigned to circles rather than individual users. Because each user is the sole member of an immutable circle named ''userid'':''userid'' permissions can be assigned per-user by assigning to that circle. Similarly, assigning to the ''projectid'':''projectid'' circle assigns permissions to all members of a project. |
| | 627 | |
| | 628 | The permissions relevant to project are: |
| | 629 | |
| | 630 | ||= Permission Name =||= Meaning || |
| | 631 | || ADD_EXPERIMENT || Circle members can add experiments to a library || |
| | 632 | || MODIFY_LIBRARY_ACCESS || Circle members can change the permissions of other circles || |
| | 633 | || READ_LIBRARY || Circle members can read experiment names and information bout access control from the library || |
| | 634 | || REMOVE_EXPERIMENT || Circle members can remove experiments from the library || |
| | 635 | |
| | 636 | A library is little more than a list of experiments. The rights to inspect, modify, or realize experiments in a library are completely controlled by the [wiki:SPIDocs#ExperimentPermissions permissions] that a user has to the experiment. Libraries provide a way to let users know that experiments exist and are related, not to control the experiments. |
| | 637 | |
| | 638 | |
| | 639 | ==== Creating A Library ==== |
| | 640 | |
| | 641 | A user creates a library using the `createLibrary` operation on the `Libraries` [wiki:SPIDocs#Services service]. Mechanically, the procedure to create a library is very similar to [wiki:SPIDocs#CreatingNewUsers creating a user] or [wiki:SPIDocs#CreatingAProject project]. An application will: |
| | 642 | |
| | 643 | * Call the `getProfileDescription` operation on the `Libraries` service to get an empty library profile |
| | 644 | * Gather data from the user to fill in the library profile, including non-optional fields and proper formatting |
| | 645 | * Call the `createLibrary` with the profile, a libraryid name from the user, and that user as the library's owner. (Administrators can create projects owned by other users). Other parameters include an initial list of experimentids in the library and initial access control lists. |
| | 646 | |
| | 647 | When `createLibrary` completes successfully, the library is ready for use. |
| | 648 | |
| | 649 | |
| | 650 | ==== Adding Experiments To A Library and Removing Them ==== |
| | 651 | |
| | 652 | The operations to add and remove experimentids from a library are pretty straightforward: `addLibraryExperiments` adds new ones and `removeLibraryExperiments` (both in the `Libraries` [wiki:SPIDocs#Services service]) do the obvious things. Both take a list of experimentids and return a result for each addition or removal. `addLibraryExperiments` requires the user to have the `ADD_EXPERIMENT` permission; `removeLibraryExperiments` requires `REMOVE_EXPERIMENT`. |
| | 653 | |
| | 654 | ==== Adding and Changing Library Access Control Lists ==== |
| | 655 | |
| | 656 | All library permissions are controlled by access control lists (ACL) that map circles to library permissions. The only exception to this is the owner of the library who always has all permissions. Any user who has `MODIFY_LIBRARY_ACCESS` permissions to an library can change its ACLs. |
| | 657 | |
| | 658 | A user can set the ACLs on `createLibrary` by providing a list of (circle, permissions) pairs, where permissions is itself a list of permissions. Any errors in specifying the ACLs will cause the creation to fail. |
| | 659 | |
| | 660 | A user can call `changeLibraryACL` with a list in the same format. New entries will be added, existing entries will be overwritten, and entries with an empty permission list will be removed. A partial success is possible and the result of each change is returned. |
| | 661 | |
| | 662 | ==== Library Ownership ==== |
| | 663 | |
| | 664 | When an library is created, an owner for that library is designated. It is generally the user who successfully called `createLibrary`, though ownership may be designated for libraries created by administrators. An owner retains all permissions to manipulate the library regardless of ACLs and controls the [wiki:SPIDocs#LibraryProfileManagement profile contents]. |
| | 665 | |
| | 666 | The owner (and administrators) can change the owner of a experiment by calling the `setOwner` operation in the `Libraries` service. |
| | 667 | |
| | 668 | ==== Library Profile Management ==== |
| | 669 | |
| | 670 | The `Libraries` [wiki:SPIDocs#Services service] supports the operations described in the [wiki:SPIDocs#Profiles profiles] description to allow applications to manipulate library profiles. Only the owner of an library can change the contents of its profile. |
| | 671 | |
| | 672 | ==== Viewing Libraries ==== |
| | 673 | |
| | 674 | A user can always view libraries that they can read. The `viewLibraries` operation on the `Libraries` [wiki:SPIDocs#Services service] returns descriptions of the various libraries. Library descriptions contain experimentid lists and ACLs. |
| | 675 | |
| | 676 | The `viewLibraries` operation takes the following parameters: |
| | 677 | |
| | 678 | ||= Parameter =||= Meaning =|| |
| | 679 | || uid || Return libraries this user can read. Admins may successfully view libraries as another user, but most users can only specify their own userid here. || |
| | 680 | || regex || Restrict returned libraries to those that have a libraryid that matches the given [http://en.wikipedia.org/wiki/Regular_expression regular expression] || |
| | 681 | || offset || Begin returning library descriptions at this position of a global list of matching libraries, ordered by creation time. This allows incremental retrieval of library lists || |
| | 682 | || count || Return only this many library descriptions || |
| | 683 | |
| | 684 | Each description contains the following information. |
| | 685 | |
| | 686 | ||= Parameter =||= Meaning =|| |
| | 687 | || library ID || The unique library identifier || |
| | 688 | || owner || The userid of the owner || |
| | 689 | || perms || The permissions that the uid can exert on the library. This allows an application to report the permissions without calculating them from the circles in the ACL || |
| | 690 | || ACL || The access control list as a list of (circle, (permissions,...) ) pairs. Permissions is a list of permissions. || |
| | 691 | || Experiments || The experimentids in the library || |
| | 692 | |
| | 693 | |
| | 694 | ==== Administrative Operations ==== |
| | 695 | |
| | 696 | There are a few more operations that are restricted to administrators. |
| | 697 | |
| | 698 | There are [wiki:SPIDocs#Profiles profile] operations to add, remove and change attributes to the circle profile schema. |
| | 699 | |
| | 700 | These are documented below. |
