Merge pull request #862 from joyent/ether/v3-organizations

v3: organizations!

docs/index.md

@@ -56,6 +56,9 @@ directory in the main repository.
 * [Conch::Route::RackLayout](modules/Conch::Route::RackLayout)
   * `/layout`
 
+* [Conch::Route::Organization](modules/Conch::Route::Organization)
+  * `/organization`
+
 * [Conch::Route::Rack](modules/Conch::Route::Rack)
   * `/rack`
 

docs/modules/Conch::Controller::Organization.md

@@ -0,0 +1,80 @@
+# NAME
+
+Conch::Controller::Organization
+
+# METHODS
+
+## list
+
+If the user is a system admin, retrieve a list of all active organizations in the database;
+otherwise, limits the list to those organizations of which the user is a member.
+
+Note: the only workspaces and roles listed are those reachable via the organization, even if
+the user might have direct access to the workspace at a greater role. For comprehensive
+information about what workspaces the user can access, and at what role, please use `GET
+/workspace` or `GET /user/me`.
+
+Response uses the Organizations json schema.
+
+## create
+
+Creates an organization.
+
+Requires the user to be a system admin.
+
+## find\_organization
+
+Chainable action that validates the `organization_id` or `organization_name` provided in the
+path, and stashes the query to get to it in `organization_rs`.
+
+Requires the 'admin' role on the organization (or the user to be a system admin).
+
+## get
+
+Get the details of a single organization.
+Requires the 'admin' role on the organization.
+
+Note: the only workspaces and roles listed are those reachable via the organization, even if
+the user might have direct access to the workspace at a greater role. For comprehensive
+information about what workspaces the user can access, and at what role, please use
+`GET /workspace` or `GET /user/me`.
+
+Response uses the Organization json schema.
+
+## delete
+
+Deactivates the organization, preventing its members from exercising any privileges from it.
+
+User must have system admin privileges.
+
+## list\_users
+
+Get a list of members of the current organization.
+Requires the 'admin' role on the organization.
+
+Response uses the OrganizationUsers json schema.
+
+## add\_user
+
+Adds a user to the current organization, or upgrades an existing role entry to access the
+organization.
+Requires the 'admin' role on the organization.
+
+Optionally takes a query parameter `send_mail` (defaulting to true), to send an email
+to the user and to all organization admins.
+
+## remove\_user
+
+Removes the indicated user from the organization.
+Requires the 'admin' role on the organization.
+
+Optionally takes a query parameter `send_mail` (defaulting to true), to send an email
+to the user and to all organization admins.
+
+# LICENSING
+
+Copyright Joyent, Inc.
+
+This Source Code Form is subject to the terms of the Mozilla Public License,
+v.2.0. If a copy of the MPL was not distributed with this file, You can obtain
+one at [http://mozilla.org/MPL/2.0/](http://mozilla.org/MPL/2.0/).

docs/modules/Conch::Controller::User.md

@@ -124,7 +124,7 @@ Optionally takes a query parameter `clear_tokens` (defaulting to true), to also
 session tokens for the user, which would force all tools to log in again should the account be
 reactivated (for which there is no api endpoint at present).
 
-All user\_workspace\_role entries are removed and are not recoverable.
+All memberships in workspaces and organizations are removed and are not recoverable.
 
 Response uses the UserError json schema on some error conditions.
 

docs/modules/Conch::Controller::WorkspaceOrganization.md

@@ -0,0 +1,41 @@
+# NAME
+
+Conch::Controller::WorkspaceOrganization
+
+# METHODS
+
+## list\_workspace\_organizations
+
+Get a list of organizations for the current workspace.
+Requires the 'admin' role on the workspace.
+
+Response uses the WorkspaceOrganizations json schema.
+
+## add\_workspace\_organization
+
+Adds a organization to the current workspace, or upgrades an existing role entry to access the
+workspace.
+Requires the 'admin' role on the workspace.
+
+Optionally takes a query parameter `send_mail` (defaulting to true), to send an email
+to all organization members and all workspace admins.
+
+## remove\_workspace\_organization
+
+Removes the indicated organization from the workspace, as well as all sub-workspaces.
+Requires the 'admin' role on the workspace.
+
+Note this may not have the desired effect if the organization is getting access to the
+workspace via a parent workspace. When in doubt, check at `GET
+/workspace/:workspace_id/organization`.
+
+Optionally takes a query parameter `send_mail` (defaulting to true), to send an email
+to all organization members and to all workspace admins.
+
+# LICENSING
+
+Copyright Joyent, Inc.
+
+This Source Code Form is subject to the terms of the Mozilla Public License,
+v.2.0. If a copy of the MPL was not distributed with this file, You can obtain
+one at [http://mozilla.org/MPL/2.0/](http://mozilla.org/MPL/2.0/).

docs/modules/Conch::DB::AsEpoch.md → docs/modules/Conch::DB::Helper::ResultSet::AsEpoch.md

@@ -1,6 +1,6 @@
 # NAME
 
-Conch::DB::AsEpoch
+Conch::DB::Helper::ResultSet::AsEpoch
 
 # DESCRIPTION
 
@@ -11,7 +11,7 @@ This code is postgres-specific.
 # USAGE
 
 ```
-__PACKAGE__->load_components('+Conch::DB::AsEpoch');
+__PACKAGE__->load_components('+Conch::DB::Helper::ResultSet::AsEpoch');
 ```
 
 # METHODS

docs/modules/Conch::DB::Deactivatable.md → docs/modules/Conch::DB::Helper::ResultSet::Deactivatable.md

@@ -1,6 +1,6 @@
 # NAME
 
-Conch::DB::Deactivatable
+Conch::DB::Helper::ResultSet::Deactivatable
 
 # DESCRIPTION
 
@@ -10,7 +10,7 @@ column, to provide common query functionality.
 # USAGE
 
 ```
-__PACKAGE__->load_components('+Conch::DB::Deactivatable');
+__PACKAGE__->load_components('+Conch::DB::Helper::ResultSet::Deactivatable');
 ```
 
 # METHODS

docs/modules/Conch::DB::ResultsExist.md → docs/modules/Conch::DB::Helper::ResultSet::ResultsExist.md

@@ -1,6 +1,6 @@
 # NAME
 
-Conch::DB::ResultsExist
+Conch::DB::Helper::ResultSet::ResultsExist
 
 # DESCRIPTION
 
@@ -14,7 +14,7 @@ This code is postgres-specific.
 # USAGE
 
 ```
-__PACKAGE__->load_components('+Conch::DB::ResultsExist');
+__PACKAGE__->load_components('+Conch::DB::Helper::ResultSet::ResultsExist');
 ```
 
 # METHODS

docs/modules/Conch::DB::Helper::ResultSet::WithRole.md

@@ -0,0 +1,28 @@
+# NAME
+
+Conch::DB::Helper::ResultSet::WithRole
+
+# DESCRIPTION
+
+A component for [Conch::DB::ResultSet](../modules/Conch::DB::ResultSet) classes for database tables with a `role`
+column, to provide common query functionality.
+
+# USAGE
+
+```
+__PACKAGE__->load_components('+Conch::DB::Helper::ResultSet::WithRole');
+```
+
+# METHODS
+
+## with\_role
+
+Constrains the resultset to those rows that grants (at least) the specified role.
+
+# LICENSING
+
+Copyright Joyent, Inc.
+
+This Source Code Form is subject to the terms of the Mozilla Public License,
+v.2.0. If a copy of the MPL was not distributed with this file, You can obtain
+one at [http://mozilla.org/MPL/2.0/](http://mozilla.org/MPL/2.0/).

docs/modules/Conch::DB::ToJSON.md → docs/modules/Conch::DB::Helper::Row::ToJSON.md

@@ -1,6 +1,6 @@
 # NAME
 
-Conch::DB::ToJSON
+Conch::DB::Helper::Row::ToJSON
 
 # DESCRIPTION
 
@@ -10,7 +10,7 @@ Sub-classes [DBIx::Class::Helper::Row::ToJSON](https://metacpan.org/pod/DBIx::Cl
 # USAGE
 
 ```
-__PACKAGE__->load_components('+Conch::DB::ToJSON');
+__PACKAGE__->load_components('+Conch::DB::Helper::Row::ToJSON');
 ```
 
 # LICENSING

docs/modules/Conch::DB::Helper::Row::WithRole.md

@@ -0,0 +1,34 @@
+# NAME
+
+Conch::DB::Helper::Row::WithRole
+
+# DESCRIPTION
+
+A component for [Conch::DB::Result](../modules/Conch::DB::Result) classes for database tables with a `role`
+column, to provide common functionality.
+
+# USAGE
+
+```
+__PACKAGE__->load_components('+Conch::DB::Helper::Row::WithRole');
+```
+
+# METHODS
+
+## role\_cmp
+
+Acts like the `cmp` operator, returning -1, 0 or 1 depending on whether the first role is less
+than, the same as, or greater than the second role.
+
+If only one role argument is passed, the role in the current row is compared to the passed-in
+role.
+
+Accepts undef for one or both roles, which always compare as less than a defined role.
+
+# LICENSING
+
+Copyright Joyent, Inc.
+
+This Source Code Form is subject to the terms of the Mozilla Public License,
+v.2.0. If a copy of the MPL was not distributed with this file, You can obtain
+one at [http://mozilla.org/MPL/2.0/](http://mozilla.org/MPL/2.0/).

docs/modules/Conch::DB::Result::Organization.md

@@ -0,0 +1,92 @@
+# NAME
+
+Conch::DB::Result::Organization
+
+# BASE CLASS: [Conch::DB::Result](../modules/Conch::DB::Result)
+
+# TABLE: `organization`
+
+# ACCESSORS
+
+## id
+
+```
+data_type: 'uuid'
+default_value: gen_random_uuid()
+is_nullable: 0
+size: 16
+```
+
+## name
+
+```
+data_type: 'text'
+is_nullable: 0
+```
+
+## description
+
+```
+data_type: 'text'
+is_nullable: 1
+```
+
+## created
+
+```perl
+data_type: 'timestamp with time zone'
+default_value: current_timestamp
+is_nullable: 0
+original: {default_value => \"now()"}
+```
+
+## deactivated
+
+```
+data_type: 'timestamp with time zone'
+is_nullable: 1
+```
+
+# PRIMARY KEY
+
+- ["id"](#id)
+
+# RELATIONS
+
+## organization\_workspace\_roles
+
+Type: has\_many
+
+Related object: [Conch::DB::Result::OrganizationWorkspaceRole](../modules/Conch::DB::Result::OrganizationWorkspaceRole)
+
+## user\_organization\_roles
+
+Type: has\_many
+
+Related object: [Conch::DB::Result::UserOrganizationRole](../modules/Conch::DB::Result::UserOrganizationRole)
+
+## user\_accounts
+
+Type: many\_to\_many
+
+Composing rels: ["user\_organization\_roles"](#user_organization_roles) -> user\_account
+
+## workspaces
+
+Type: many\_to\_many
+
+Composing rels: ["organization\_workspace\_roles"](#organization_workspace_roles) -> workspace
+
+# METHODS
+
+## TO\_JSON
+
+Include information about the organization's admins and workspaces.
+
+# LICENSING
+
+Copyright Joyent, Inc.
+
+This Source Code Form is subject to the terms of the Mozilla Public License,
+v.2.0. If a copy of the MPL was not distributed with this file, You can obtain
+one at [http://mozilla.org/MPL/2.0/](http://mozilla.org/MPL/2.0/).