// Set namespace
namespace perl StackableControl
namespace rb StackableControl
namespace py StackableControl
namespace java StackableControl
namespace csharp StackableControl
namespace php StackableControl
namespace cpp StackableControl

// Email Address
// @validate    length  1-64
typedef string EmailAddress

// Generic IP address structure
// @validate    regex   /^(?:\d{1,3}\.){3}\d{1,3}$/
typedef string IPAddress

// @validate   range  0-32
typedef i16 CIDRMask

// Generic Hostname
// @validate    length  1-128
// @validate    regex   /^(?:(?:(?:[a-zA-Z0-9][-a-zA-Z0-9]*)?[a-zA-Z0-9])[.])*(?:[a-zA-Z][-a-zA-Z0-9]*[a-zA-Z0-9]|[a-zA-Z])$/
typedef string Hostname

// URL
// @validate    length  1-512
typedef string URL

// Time expressed in epoch
// @validate    range   0-4294967295
typedef i32 UnixTime

// Log Entry
struct LogLine {
    1: UnixTime time,
    2: string line    # @utf8
}

// Collection of log entries.
typedef list<LogLine> LogLines

/*
    Structure which defines an interval
*/
struct TimeInterval {
    1: UnixTime startTime,
    2: UnixTime endTime,
}

// Defines a security role
// @validate    regex   /^(customer|internal)$/
typedef string Role

// List of Roles
typedef list<Role> Roles

// Unique id number for a container.
// @validate    range   100-8886880
typedef i32 ContainerId
// Internal uuid for a container
// @validate    regex   /^[[:alnum:]]{8}-[[:alnum:]]{4}-[[:alnum:]]{4}-[[:alnum:]]{4}-[[:alnum:]]{12}$/
typedef string ContainerUuid
// Friendly container name
// @utf8 @validate    length  1-38
typedef string ContainerName
// Path for provisioned container storage from the perspective of the storage server
// @role        internal
// @utf8 @validate    length  1-
typedef string ContainerStoragePath
// Filesystem path
// @utf8 @validate    length  1-
typedef string Path

// Set of valid Container Operating Systems
enum ContainerOS {
    stackable_1_x86_64, CentOS_5_x86_64
}

// Set of Container resource sizes
enum ContainerSize {
    _256M, _512M, _1G,
    _2G, _4G, _8G, _16G
}

// Set of valid Container stacks
enum ContainerStack {
    PHP, LAMP
}

typedef i16 ContainerTypeId

// Struct to define the type of a container or site environment stack
struct ContainerType {
    1: ContainerTypeId id,
    2: string name,
    3: string version,
    4: bool isSiteHost,
    5: bool isDatabase,
    6: bool isInternal,
    7: bool isAvailable,
    8: bool isBeta,
}

// Unique ID for a Site
// @validate    range   1-65535
typedef i16 SiteId

// Friendly name for a site
// @utf8 @validate    length  1-64
typedef string SiteName

// Unique id for a Site's Alias
typedef i16 SiteAliasId

// Hostname (fqdn) for a Site
// @validate    length  1-128
// @validate    regex   /^(?:(?:(?:[a-zA-Z0-9][-a-zA-Z0-9]*)?[a-zA-Z0-9])[.])*(?:[a-zA-Z][-a-zA-Z0-9]*[a-zA-Z0-9]|[a-zA-Z])$/
typedef string SiteAlias

// List of SiteAliases by id
typedef map<SiteAliasId,SiteAlias> SiteAliasList

// Document Root for a site environment
// @utf8 @validate    length  1-
typedef string EnvironmentDocumentRoot

// Unique id for a Site Environment's Alias
typedef i16 EnvironmentAliasId

// Hostname (fqdn) for a Site Environment
// @validate    length  1-128
// @validate    regex   /^(?:(?:(?:[a-zA-Z0-9][-a-zA-Z0-9]*)?[a-zA-Z0-9])[.])*(?:[a-zA-Z][-a-zA-Z0-9]*[a-zA-Z0-9]|[a-zA-Z])$/
typedef string EnvironmentAlias

// List of SiteAliases by id
typedef map<EnvironmentAliasId,EnvironmentAlias> EnvironmentAliasList

// Unique id number for an environment
// @validate    range   1-65535
typedef i16 EnvironmentId

// Map of EnvironmentIds and a TimeInverval in which that EnvironmentId was configured as Live
typedef map<EnvironmentId, TimeInterval> LiveEnvironmentHistory

// Environment Name
// @utf8 @validate    length  1-64
typedef string EnvironmentName

// Unique id for a Database
// @validate   range   1-65535
typedef i16 DatabaseId
typedef i32 DatabaseUserId

// Unique id for a DatabaseBackup
typedef string DatabaseBackupId

// Username for a Database
// Usernames will be prefixed with the four character customer digest and an underscore ('_')
// @validate   length  1-16
typedef string DatabaseUser

// Name for a Database
// Names will be prefixed with the four character customer digest and an underscore ('_')
// @validate   length  1-64
typedef string DatabaseName

// @validate length 1-128
typedef string DatabasePassword

// Valid types for a Database
enum DatabaseType {
    MySQL_5_0, PostgreSQL_8_4
}

enum DatabaseUserType {
    ReadWrite, ReadOnly
}

// Record for a database backup.
struct DatabaseBackup {
    1: DatabaseBackupId id,
    2: DatabaseName database,
    3: URL backupURL,
    5: i32 size,
    6: UnixTime timestamp,
}

/*
    Details for a shared database
*/
struct DatabaseDetails {
    1: DatabaseId   id,
    2: DatabaseName name,
    3: DatabaseName friendlyName,
    4: DatabaseType type,
    5: Hostname     host,
    6: list<Hostname> replicas,
}

/*
    Details for a shared database user
*/
struct DatabaseUserDetails {
    1: DatabaseId                databaseId,
    2: DatabaseUserId            id,
    3: DatabaseUser              username,
    4: optional DatabasePassword password,   # If storePassword wasn't true when the user was created or updateUser was called, this will be unset
    5: DatabaseUserType          userType,
    6: list<Hostname>            hostsAllow, # If empty, all hosts are permitted.  Otherwise, only those listed.
    7: optional bool             pgDatabaseOwner, # For PostgreSQL databases, one user is the designated owner of the database
}

/*
    The result of a Database.create or .clone call
*/
struct DatabaseCreateResult {
    1: DatabaseDetails database,
    2: DatabaseUserDetails user,
}

/*
    An access control rule for PostgreSQL database users
*/
struct DatabasePostgreACL {
    1: IPAddress address,
    2: CIDRMask  cidr,
    3: optional bool deny, # If true, rule is to deny rather than allow
}

/*
    Wrapper for db rows from CustomerDatabaseUserSlowLog
*/
struct DatabaseSlowLog {
    1: DatabaseId     databaseId,
    2: DatabaseUserId userId,
    3: UnixTime       time,
    4: i32            rowsRead,
    5: i32            rowsAffected,
    6: i32            rowsExamined,
    7: i32            rowsSent,
    8: i16            queryTime,
    9: i16            lockTime,
    10: string        queryPartial,
    11: i16           queryLength,
}

// Unique id for a Customer
// @validate   range   1-65535
typedef i16 CustomerId

/*
 *  DNS related types
 */

typedef i32 DomainId
typedef i32 DomainRecordId

// @validate length 1-255
// @validate regex  /^\S+$/
typedef string DomainName

// @validate length 1-255
// @validate regex  /^\S+$/
typedef string DomainRecordName

// Set of valid NS record types.  Some of these may not be supported by PowerDNS
// Omitting: IPSECKEY, NXT, KEY, DS, RRSIG, NSEC, DNSKEY, DLV, NSEC3, NSEC3PARAM
// The SOA record will be updated automatically
enum DomainRecordType {
    A, AAAA, AFSDB, APL,
    CNAME, CERT, DNAME,
    EID, HINFO, ISDN, LOC,
    MB, MG, MINFO, MR, MX,
    NAPTR, NIMLOC, NS, NSAP, NULL,
    OPT, PTR, PX, RP, RT,
    SOA, SRV, SSHFP, SPF,
    TKEY, TSIG, TXT, X25
}

// @validate length 1-255
typedef string DomainRecordContent

// @validate range 60-
typedef i32 DomainRecordTTL

// @validate range 0-255
typedef i16 DomainRecordPriority

/*
 *  CertificateAuthority related types
 */

// @validate regex /^[A-Z]{2}$/
// @validate length 2-2
typedef string CACountry
typedef string CAStateProvince
typedef string CACityLocality
typedef string CAOrganization
typedef string CAOrganizationUnit
// @validate length 1-
typedef string CACommonName
// @validate range 1-3650
typedef i16    CADays

typedef string PEMString
// @validate length 8-8
typedef string CAHash

typedef i32    CSRId
typedef i32    CertificateId

// Setting Key
// @validate    length  1-128
typedef string SettingKey

// Setting Value
// @utf8 @validate    length  1-128
typedef string SettingValue

// Map of SettingKeys and their SettingValue
typedef map<SettingKey, SettingValue> SettingList

typedef i32 SettingId
typedef i32 ObjectSettingId
typedef i32 ObjectId

// @validate    length  1-128
typedef string SettingSelectKey
typedef string SettingClass
typedef string SettingName

/*
        STRUCTURES

*/

enum SettingType {
    Boolean, Switch, Number, Select, String
}

/*
    Setting context, from related_setting_obj_id()
*/
enum ObjectSettingContext {
    Customer = 0,
    Site = 1,
    SiteEnvironment = 2,
    Container = 3,
    ContainerSiteEnvironment = 4
}

/*
    An objects setting
*/
struct ObjectSetting {
    1: ObjectSettingId       id,
    2: ObjectSettingContext  context,
    3: ObjectId              objectId,
    4: optional string       objectName, # @utf8
    5: SettingId             settingId,
    6: optional SettingValue value,
    7: optional SettingValue defaultValue,
}

/*
    Select option pair for the setting catalog
*/
struct SettingSelectOption {
    1: SettingSelectKey key,
    2: SettingValue value,
}

/*
    A setting catalog item
*/
struct SettingCatalog {
    1: SettingId    id,
    2: SettingType  type,
    3: SettingKey   key,
    4: SettingClass settingClass,
    5: SettingName  name,
    6: optional SettingValue defaultValue,
    7: list<ObjectSettingContext> contexts,
    8: list<SettingSelectOption> selectOptions,
    9: optional URL url,
    10: optional string description,
}

/*
    # Resources with 'count' single value
    TrafficIncomingBytes,
    TrafficIncomingPackets,
    TrafficOutgoingBytes,
    TrafficOutgoingPackets,

    # Resources with 'load' single value
    LoadAverage,
    LoadAverage5Minute,
    LoadAverage15Minute,

    # Resources with a 'used', 'soft', 'hard' and 'percent'
    CPU,
    DiskInode,
    # ... and 'unit'
    Memory,
    Disk,
*/

enum ResourceUsageType {
    TrafficIncomingBytes,
    TrafficIncomingPackets,
    TrafficOutgoingBytes,
    TrafficOutgoingPackets,
    LoadAverage,
    LoadAverage5Minute,
    LoadAverage15Minute,
    CPU,
    Memory,
    Disk,
    DiskInode,
    TrafficTotal
}

enum ResourceUsageUnit {
    Byte, KByte, MByte, GByte
}

/*
    An all-optional representation of the value of a single resource
*/
struct ResourceUsage {
    1: optional ResourceUsageUnit unit,
    2: optional double used,
    3: optional double soft,
    4: optional double hard,
    5: optional double percent,
    6: optional i32    count,
    7: optional double load,
}

/*
    Current resource usage for a container.
    The records map could look something like this:
    {
        TrafficIncomingBytes: {
            count: 654593,
        },
        CPU: {
            used:  28.00,
            hard: 200.00,
        },
        LoadAverage: {
            load: 1.8
        },
        Disk: {
            unit: MByte,
            used:  191916.00,
            soft: 1048576.00,
            hard: 1048576.00,
        },
        Memory: {
            unit: Byte,
            used:  21372928.00,
            hard: 268435456.00,
        },
    }
    As you can see, the fields used in the ResourceUsage struct are context sensitive
*/
struct ResourceCurrentUsage {
    1: UnixTime time,
    2: i32      uptime,     # Seconds since last reboot
    3: map< ResourceUsageType, ResourceUsage > records,
}

/*
    Moment in time resource usage for a container.
    The records map could look something like this:
    {
        TrafficIncomingBytes: {
            count: 654593
        },
        CPU: {
            percent: 18.11
        },
        LoadAverage: {
            load: 1.8
        },
        Disk: {
            percent: 2.51
        },
    }
    This is a different result than 'ResourceCurrentUsage', as each record has an average-type value and has no limit or type indication
*/
struct ResourceHistoricalUsage {
    1: UnixTime startTime,
    2: UnixTime endTime,
    3: map< ResourceUsageType, ResourceUsage > records,
}

/*
    A single process, sampled at a moment in time, running on a container
*/
struct Process {
    1: string cmd,
    2: string comm,
    3: i32    pid,
    4: optional i32 ppid, # Parent pid; init doesn't have a parent
    5: optional i32 npid, # Node pid
    6: i32    uid,
    7: i32    gid,
    8: UnixTime startTime,
    9: i16    cpu,
    10: i32   rss,
}

/*
    A sample of all the processes running on a container at a moment in time
*/
struct ProcessTable {
    1: ContainerId containerId,
    2: UnixTime    time,
    3: list<Process> processes,
}

/*
    The metrics one can get a graph of process table data
*/
enum ProcessTableMetric {
    RSS, CPU
}

/*
    A single process and a list of graph data for metric(s)
    No context for this data.
*/
struct ProcessTableGraphProcess {
    1: Process process,
    2: map<ProcessTableMetric,list<list<i32>>> data, # { $metric: [ [ $offset, $value ], [ $offset, $value ], ... ] }
}

/*
    A graph of process data over a period of time
    See Container.getProcessTableGraph
*/
struct ProcessTableGraph {
    1: ContainerId containerId,
    2: UnixTime    startTime,
    3: UnixTime    endTime,
    4: i32         intervalTime,
    5: optional i16 limit,
    6: list<ProcessTableMetric> metrics,
    7: map<ProcessTableMetric,i32> thresholds,
    8: list<ProcessTableGraphProcess> processes,
}

/*
    An event indicating a moment when memory was running out on a container and an effort
    was made to kill a process using too much memory.  If not isKilled, indicates only that
    a signal was sent.  Due to a flaw in the reporting system, there's no guarantee that
    a signal will be followed by an isKilled event, and vice versa.  True success is
    not indicated.
*/
struct ContainerOOMEvent {
    1: ContainerId containerId,
    2: UnixTime    time,
    3: i32         npid, # Node process id; can be correlated using a Process (from ProcessTableGraph or ProcessTable)  to the container process id
    4: string      process,
    5: optional bool isKilled,
}

typedef i16 ContainerCommandId

/*
    Struct of both the spec and passed value of arguments
*/
struct ContainerCommandArgument {
    1: optional string value,
    2: optional string description,
    3: optional list<string> options,
    4: optional bool isRequired,
    5: optional bool isFreeform,
    6: optional string defaultValue,
}

/*
    A command one can call against a container
*/
struct ContainerCommand {
    1: ContainerCommandId id,
    2: string name,
    3: list<ContainerCommandArgument> arguments,
}

/*
    The result of a command called against a container
*/
struct ContainerCommandResponse {
    1: ContainerId containerId,
    2: ContainerCommandId containerCommandId,
    3: list<ContainerCommandArgument> arguments,
    4: i16    status,
    5: string stderr,
    6: string stdout,
}

/*
    A list of computed object settings
    with the related catalog
*/
struct ComputedObjectSettings {
    1: ObjectSettingContext context,
    2: ObjectId             objectId,
    3: list<SettingId>      catalog,
    4: list<ObjectSetting>  settings,
}

enum ContainerStatus {
    Okay, Warning, Critical, Off, Unknown
}

/*
    Returned from some Container.* calls

    @param  customerId  Id of the owning Customer
    @param  id          Unique ID for the container
    @param  uuid        Universally unique ID for the container
    @param  address     Public ip address for the container
    @param  name        Container name
    @param  os          Operating System installed on the container
    @param  stack       Stack installed on the container
    @param  hostname    Hostname for the container (xxx.digest.stackablehost.com)
    @param  environments List of Environments this container serves.

*/
struct ContainerDetails {
    1: CustomerId customerId,
    2: ContainerId id,
    3: ContainerUuid uuid,
    4: IPAddress address,
    5: ContainerName name,
    6: ContainerOS os,
    15: ContainerTypeId type,
    8: Hostname hostname,
    9: list<EnvironmentId> environments,
    10: ContainerSize size,
    11: ContainerStatus status,
    12: ContainerStatus statusCurrent,
    13: ContainerStatus statusRecent,
    14: optional ResourceCurrentUsage latestResourceUsage,
}

enum ContainerHistoricalStatusName {
    unknown = 0,
    non_existent = 1,
    config = 2,
    down = 3,
    mounted = 4,
    suspended = 5,
    running = 6,
    repairing = 7,
    license_violation = 8
}

enum ContainerHistoricalTransitionName {
    none = 0,
    unknown = 1,
    creating = 2,
    mounting = 3,
    starting = 4,
    stopping = 5,
    unmounting = 6,
    destroying = 7,
    moving = 8,
    cloning = 9,
    migrating = 10,
    starting_repair = 11,
    stopping_repair = 12,
    setting = 13,
    updating = 14,
    backing_up = 15,
    restoring = 16,
    reinstalling = 17,
    suspending = 18,
    resuming = 19,
    restarting = 20
}

/*
    A past Container status
*/
struct ContainerHistoricalStatus {
    1: ContainerId containerId,
    2: UnixTime    time,
    3: ContainerHistoricalStatusName     statusNew,
    4: ContainerHistoricalTransitionName transitionNew,
    5: ContainerHistoricalStatusName     statusOld,
    6: ContainerHistoricalTransitionName transitionOld,
}

enum ContainerHistoricalAlertCounter {
    counter_cpu_share_used = 1,
    counter_memory_share_used = 2,
    diskspace = 3,
    quotaugidlimit = 4,
    slmmemorylimit = 5,
    counter_disk_share_used = 6,
    diskinodes = 7
}

enum ContainerHistoricalAlertType {
    green = 0, yellow = 1, red = 2
}

/*
    A past Container alert
*/
struct ContainerHistoricalAlert {
    1: ContainerId containerId,
    2: UnixTime    time,
    3: ContainerHistoricalAlertCounter counter,
    4: i32 soft,
    5: i32 hard,
    6: i32 current,
    7: ContainerHistoricalAlertType type,
}

/*
    A representation of most all the data found in haproxy stats
*/
struct LoadBalancerStatus {
    1: UnixTime time,
    2: SiteId siteId,
    3: optional EnvironmentId environmentId,
    4: optional ContainerId containerId,
    5: i32 bytesIn,
    6: i32 bytesOut,
    7: optional i16 connectionErrors,
    8: optional i16 requestErrors,
    9: optional i16 deniedRequests,
    10: optional i16 deniedResponses,
    11: optional i16 redispatchesWarning,
    12: optional i16 retriesWarning,
    13: i16 currentSessions,
    14: i16 maxSessions,
    15: i32 totalSessions,
    16: i16 sessionsLimit,
    17: i16 maxQueue,
    18: i16 currentQueue,
    19: bool serverIsUp,
    20: optional i32 serverDowntime,
    21: optional i16 serverUpDownTransitions,
    22: optional i16 serverFailedChecks,
    23: optional i16 serversInBackend,
    24: optional i16 serversUpInBackend,
}

/*
    All the LoadBalancerStatus records that are associated with the live site
*/
struct SiteLoadBalancerStatus {
    1: SiteId siteId,
    2: UnixTime time,
    3: LoadBalancerStatus frontendStatus,
    4: list<LoadBalancerStatus> backendStatus,
}

/*
    Structure which defines the storage for a Container

    @param  provisioned     boolean value indicating if storage has actually been provisioned
*/
struct ContainerStorage {
    1: bool provisioned,
}

/*
    Container configuration for a specific environment

    @param id
    @param uuid
    @param name
    @param address
    @param hostname     Speical hostname for this ContainerSiteEnvironment
*/
struct ContainerEnvironmentDetails {
    1: ContainerId id,
    3: ContainerUuid uuid,
    4: ContainerName name,
    5: IPAddress address,
    6: Hostname hostname,
    7: EnvironmentDocumentRoot docroot
    8: bool isMaster,
    9: EnvironmentId environmentId,
    10: EnvironmentName environmentName,
    11: Hostname siteHostname,
    12: bool isLive,
    13: ContainerTypeId type,
    14: SiteId siteId,
}

/*
    Details for an Environment

    @param id           Environment ID
    @param name         Environment name
    @param port         Unique port number for the Environment
    @param luid         Customer-unique id for the Environment
    @param hostname     Environment-specific hostname
    @param settings     List of settings for the Environment
    @param aliases      List of Environment aliases (hostnames)
    @param containers   List of ContainerIds configured for this Environment
*/
struct EnvironmentDetails {
    1: EnvironmentId id,
    2: EnvironmentName name,
    3: i16 port,
    4: i16 luid,
    6: Hostname hostname,
    7: EnvironmentDocumentRoot docroot,
    8: SettingList settings,
    9: EnvironmentAliasList aliases,
    10: list<ContainerEnvironmentDetails> containers,     # FIXME: doesn't map to old data structure (lacking)
    11: bool isLive,
    12: ContainerTypeId type,
}

/*
    Site ip addresses

    @param address  the ip address
    @param ssl      boolean declaring if this address is reserved for ssl
    @param sites    list of sites this ip address hosts
*/
struct SiteAddress {
    1: IPAddress address,
    2: bool ssl,
    3: list<SiteId> sites,
}

enum SiteStatus {
    Okay, Warning, Critical, Unknown
}

/*
    Site Details
*/
struct SiteDetails {
    1: SiteId id,
    2: SiteName name,
    3: Hostname hostname,
    4: Hostname stackableHostname,
    5: SiteStatus status,
    6: IPAddress address,
    7: SiteAliasList aliases,
    8: SettingList settings,
    9: list<EnvironmentDetails> environments,
    10: bool isSSLReserved,
    11: optional CertificateId certificateId,
}

// Valid container states
enum ContainerState {
    stopped, running, repairing, unknown
}

// Valid container transitions
enum ContainerTransition {
    creating, mounting, starting,
    stopping, unmounting, destroying,
    updating, setting
}

/*
    Container event

    @param id               the id of the container
    @param time             the time the event occurred
    @param oldState         the old state of the container
    @param oldTransition    the old transition state
    @param newState         the new state of the Container
    @param newTransition    the new transition for the container
    @param log              any log entries associated with this event.

*/
struct ContainerEvent {
    1: ContainerId id,
    2: UnixTime time,
    3: ContainerState oldState,
    4: ContainerTransition oldTransition,    # @optional
    5: ContainerState newState,
    6: ContainerTransition newTransition,    # @optional
    7: LogLines log
}

/*
    Container manifest

    @param id           Container id.
    @param manifest     Puppet manifest for the node.

*/
struct ContainerManifest {
    1: ContainerId id,
    2: string manifest
}

/*
    Representation of the subject of a CSR and Certificate
    @param hash Will be auto-computed; you don't need to provide it
*/
struct DistinguishedName {
    1: CACountry       country,
    2: CAStateProvince state,
    3: CACityLocality  city,
    4: CAOrganization  organization,
    5: optional CAOrganizationUnit unit,
    6: CACommonName    commonName,
    7: EmailAddress    email,
    8: optional CAHash hash,
}

/*
    An alternative name for a certificate
    Provide either 'dns' or 'ip' but not both.
*/
struct SubjectAltName {
    1: optional DomainName dns,
    2: optional IPAddress  ip,
}

/*
    Types of CSRVerifications.

    DNSCode:
      - The CSRVerification.data map will contain a value called 'cname'
      - Create this 'cname' DNS record as a CNAME record, pointing to 'stackable.com'
        For example, if you have a CSR for the name 'www.mydomain.com', to have you
        prove that you are in control of 'mydomain.com', you'll need to create a
        DNS record like so:

          vi7twuHyel8.mydomain.com. IN CNAME stackable.com.

        The process to create this CNAME record will vary depending on your DNS
        provider.

*/
enum CSRVerificationType {
    DNSCode
}

/*
    Data necessary to verify a CSR
*/
struct CSRVerification {
    1: CSRId               id,
    2: CSRVerificationType type,
    3: map<string,string>  data,
}

/*
    Indication of verified Certificate
    @param siteReady Indicates if the Certificate can be installed via Site.assignCertificate
*/
struct CertificateVerification {
    1: bool isValid,
    2: string message,
    3: bool siteReady,
}

/*
    Representation of a Certificate Signing Request
    If the list 'verifies' has data, the CSR cannot yet be used for creating
    a certificate.  You must fulfill the verification mechanism for it to be
    verified.  The subject common name and all DNS alt names must be verified.
*/
struct CSR {
    1: CSRId                id,
    2: CustomerId           customerId,
    3: PEMString            request,
    4: DistinguishedName    subject,
    5: list<SubjectAltName> altNames,
    6: optional list<CSRVerification> verifies,
}

/*
    A CSR with the private optionally included
*/
struct CSRMeta {
    1: CSR                csr,
    2: optional PEMString privateKey,
}

/*
    Representation of an SSL certificate
    If 'verify'.'isValid' is not true, the certificate cannot be installed
    onto a Site.  See 'verify'.'message' for the reason why it's not valid.
*/
struct Certificate {
    1: CertificateId     id,
    2: CustomerId        customerId,  # @optional
    3: PEMString         certificate,
    4: UnixTime          validFrom,
    5: UnixTime          validTo,
    6: DistinguishedName subject,
    7: DistinguishedName issuer,
    8: list<SubjectAltName> altNames,
    9: CertificateVerification verify,
    10: optional SiteDetails associatedSite,
}

/*
    A Certificate with optionally the CSR and private key
*/
struct CertificateMeta {
    1: Certificate        certificate,
    2: optional CSR       csr,
    3: optional PEMString privateKey,
    4: optional list<Certificate> chain,
}

/*
    Structure encapsulating a DNS check
*/
struct DNSCheck {
    1: bool successful,
    2: string error,
    3: bool unknown,
    4: optional IPAddress address,
    5: optional Hostname hostname,
    6: optional string type,
}

/*
    A representation of a domain
*/
struct DomainDetails {
    1: DomainId id,
    2: optional CustomerId customerId,
    3: DomainName name,
    4: optional DNSCheck dnsCheck,
}

/*
    A representation of a domain record
*/
struct DomainRecordDetails {
    1: DomainRecordId        id,
    2: DomainId              domainId,
    3: DomainRecordName      name,
    4: DomainRecordType      type,
    5: DomainRecordContent   content,
    6: optional DomainRecordTTL       ttl,
    7: optional DomainRecordPriority  priority,
}

/*
    A representation of a CustomerAddress record
*/
struct CustomerAddressDetails {
    1: CustomerId customerId,
    2: IPAddress  address,
    3: bool       isSslAvailable,  # True if no site is using this IP with SSL reserved
    4: map<SiteId, bool> sites,    # List of sites that use this IP, and a bool flag indicating if SSL is reserved for this site
}

enum IPAddressDetailsType {
    Site, Environment, Container
}

/*
    Optional sub-struct of IPAddressDetails
*/
struct IPAddressDetailsSite {
    1: SiteId   id,
    2: SiteName name,
    3: Hostname hostname,
    4: DNSCheck dnsCheck,
    5: Hostname stackableHostname,
    6: bool     isSSLReserved,
    7: map<SiteAlias, DNSCheck> aliases,
}

/*
    Optional sub-struct of IPAddressDetails
*/
struct IPAddressDetailsEnvironment {
    1: EnvironmentId   id,
    2: EnvironmentName name,
    3: Hostname        stackableHostname,
    4: map<EnvironmentAlias, DNSCheck> aliases,
}

/*
    Generic, typed struct for all Customer-referenced address details
*/
struct IPAddressDetails {
    1: IPAddressDetailsType type,
    2: IPAddress            address,
    3: optional bool        isSSLReserved, # used only for type 'Site'
    4: optional Hostname    hostname,      # used only for type 'Container'
    5: list<IPAddressDetailsSite> sites,               # used only for type 'Site'
    6: list<IPAddressDetailsEnvironment> environments, # used only for type 'Environment'
}

typedef i32 CustomerNoticeId

/*
    A customer notice of an time-sensitive issue
*/
struct CustomerNotice {
    1: CustomerNoticeId id,
    2: string   message,
    3: UnixTime created,
    4: optional UnixTime updated,
    5: optional UnixTime acknowledged,
    6:          UnixTime startTime,
    7: optional UnixTime endTime,
    8: bool     isActive,
    9: bool     isGlobal,
}

// Set of valid Customer types
enum CustomerType {
    GENERAL, RESELLER, INTERNAL
}
// Customer Name
// @utf8 @validate   length  -64
typedef string CustomerName
// Customer Unix Username
// @validate   regex   /^\w{2,16}$/
typedef string CustomerUsername

// Unique id for an APIKey
typedef i32 APIKeyId

typedef i32 APIKeyACLId

// Secret content of an APIKey
// @validate   regex   /^[[:alnum:]]{32}$/
typedef string SecretKey

/*
    Structure of an API key's ACL entry
*/
struct APIKeyACL {
    1: APIKeyACLId id,
    2: APIKeyId keyId,
    3: IPAddress address,
    4: CIDRMask cidr,
}

enum APIKeyType {
    Provider, ControlPanel, Customer, Internal, Container
}

typedef i32 FTPUserId

enum FTPUserType {
    ReadOnly, ReadWrite
}

/*
    A single Customer-controlled FTP user
*/
struct FTPUser {
    1: FTPUserId        id,
    2: CustomerId       customerId,
    3: CustomerName     name,
    4: CustomerUsername username,
    5: string           relativeRoot,  # @utf8
    6: FTPUserType      type,
    7: optional SiteId        siteId,
    8: optional EnvironmentId environmentId,
}

/*
    Structure representing an API key
*/
struct APIKey {
    1: APIKeyId id,
    2: SecretKey key,
    3: CustomerId customerId,
    4: Roles roles,
    5: list<APIKeyACL> acls,
    6: APIKeyType type,
}
// List of APIKeys by id
typedef list<APIKey> APIKeys

/*
    Customer configuration
*/
struct CustomerConfig {
    1: CustomerId id,
    2: CustomerName name,
    3: CustomerUsername username,
    4: EmailAddress email,
    5: SettingList settings,
}


typedef i32 PBA_accountId
typedef i32 PBA_subscriptionId
typedef i32 PBA_planId
typedef i32 PBA_planPeriodId
typedef i32 PBA_paymentMethodId
typedef i32 PBA_resourceId
typedef i32 PBA_orderId
typedef i32 PBA_arDocId
typedef i32 PBA_invitationId

enum PBA_accountRole {
    Reseller = 2,
    Customer = 3
}

enum PBA_accountType {
    Person = 1,
    Company = 2
}

enum PBA_paySystem {
    Visa, MasterCard, American_Express, Discover
}

enum PBA_payType {
    Credit_Card, Bank_Account, External_Redirect, Check_Cash
}

enum PBA_periodType {
    Hour, Day, Month, Year
}

enum PBA_orderStatus {
    AR_Document_Check,
    Approved,
    Approved_for_Processing,
    CC_Charge_Failed,
    CC_Pre_Auth_Failed,
    Cancelled,
    Charging_CC,
    Check_if_Number_of_Attempts_Exceeded,
    Completed,
    Credit_Limit_is_exceeded,
    Fraud,
    Fraud_2,
    Fraud_Screening,
    Fraud_Screening_Completed,
    Hold,
    Intermediate_for_AR_Doc_creation,
    Invoice_Created,
    Long_Running_Operation,
    Manual_Customer_Account_Verification_is_not_required,
    Manual_Customer_Account_Verification_is_required,
    Manual_Operation_Not_Required,
    Manual_Operation_Required,
    New,
    New_CC_Attached,
    Open,
    Order_contains_Provisioning_Items,
    Paid_or_Payment_is_postponed,
    Payment_Method_not_Attached,
    Payments_are_Received,
    Preauthorization_Completed,
    Preauthorizing,
    Provisioned,
    Provisioning,
    Provisioning_Failed,
    Provisioning_Not_Completed,
    Provisioning_Not_Failed,
    Suspected,
    Waiting_Timeout_to_Resubmit_Payment,
    Waiting_for_Approval,
    Waiting_for_Payment
}

enum PBA_subscriptionStatus {
    Ordered    = 10,
    Trial      = 15,
    Active     = 30,
    Graced     = 40,
    Expired    = 50,
    Terminated = 60,
    Canceled   = 70,
    Suspended  = 80
}

enum PBA_subscriptionServiceStatus {
    Not_Provisioned = 10,
    Provisioning    = 20,
    Stopped         = 30,
    Starting        = 40,
    Running         = 50,
    Stopping        = 60,
    Removing        = 70,
    Changing_Plan   = 80,
    Removed         = 90
}

enum PBA_recurringType {
    Before_billing_period      = 10,
    After_billing_period       = 20,
    Before_subscription_period = 30,
    End_of_month               = 40
}

enum PBA_billingPeriodType {
    Months_fixed = 2,
    Years_fixed  = 3,
    Monthly_on_statement_cycle_date = 4
}

enum PBA_arDocType {
    AR_DOCUMENTS   = 20,
    PAYMENT        = 50,
    REFUND         = 70,
    VOID_CHECK     = 75,
    AR_DOCUMENTS_2 = 80,
    AR_DOCUMENTS_3 = 90,
    FRAUD_CHECK    = 100
}

enum PBA_arDocStatus {
    Hold      = 2000,
    Open      = 1000,
    Closed    = 3000,
    Cancelled = 6000
}

/*
    Found in Configuration Director   >  Miscellaneous Settings   >  Reason Codes
*/
enum PBA_reasonCode {
    Start_Service_Customer_Request          = 1,
    Start_Service_Released_from_Credit_Hold = 2,
    Start_Service_Other                     = 3,
    Start_Service_Not_Applicable            = 4,

    Stop_Service_Customer_Request           = 5,
    Stop_Service_Fraud                      = 6,
    Stop_Service_Account_overdue            = 7,
    Stop_Service_AUP_Violation              = 8,
    Stop_Service_Other                      = 9,
    Stop_Service_Not_Applicable             = 10,

    Cancel_by_Customer_Customer_Request     = 11,
    Cancel_by_Customer_Other                = 12,

    Cancel_by_Vendor_Customer_Request     = 13,
    Cancel_by_Vendor_Other                = 14,

    Account_Cancellation_Customer_Request = 15,
    Account_Cancellation_Other            = 16,

    Destroy_Service_Account_overdue     = 61,
    Destroy_Service_Other               = 69
}

enum PBA_cancelType {
    Customer_refunded = 10,
    Customer_credited = 20,
    Customer_not_refunded_credited = 30
}

/* Phone number */
struct PBA_PhoneNumber {
    1: string countryCode,        # @validate length 1-4
    2: optional string areaCode,  # @validate length 1-10
    3: string number,             # @validate length 1-20
    4: optional string extension, # @validate length -10
}

/* Address */
struct PBA_Address {
    1: string address,   # @utf8 @validate length 1-80
    2: optional string address2,  # @utf8 @validate length -80
    3: string city,      # @utf8 @validate length 1-40
    4: string state,     # @utf8 @validate length 1-80
    5: string zip,       # @validate length 1-10
    6: string countryId, # @validate length 2-2 @validate regex /^[a-z]{2}$/
}

/* Contact */
struct PBA_Contact {
    1: string firstName,           # @utf8 @validate length 1-30
    2: optional string middleName, # @utf8 @validate length -30
    3: string lastName,            # @utf8 @validate length 1-30
    4: string email,               # @validate length 1-100
    5: PBA_PhoneNumber phone,
    6: optional PBA_PhoneNumber fax,
}

/* Subscription */
struct PBA_Subscription {
    1: PBA_subscriptionId id,
    2: string             name,  # @utf8
    3: PBA_planId         planId,
    4: string             planName,
    5: PBA_planPeriodId   planPeriodId,
    6: i16                period,
    7: PBA_periodType     periodType,
    8: UnixTime           startDate,
    9: UnixTime           expirationDate,
    10: PBA_subscriptionStatus status,
    11: PBA_subscriptionServiceStatus serviceStatus,
}

/* Subscription order */
struct PBA_SubscriptionOrder {
    1: PBA_orderId        orderId,
    2: PBA_subscriptionId subscriptionId,
    3: string creationTimeStr,
    4: i32    paymentDocumentId,
    5: double total,
    6: double taxTotal,
    7: double discountTotal,
    8: double merchTotal,
    9: string description, # @utf8
}

/* Plan */
struct PBA_Plan {
    1: PBA_planId  id,
    2: string      name,
    3: string      shortDescription,
    4: string      longDescription,
    5: bool        isPublished,
    6: PBA_recurringType recurring,
    7: PBA_billingPeriodType billingPeriodType,
    8: i16         billingPeriod,
}

/* Plan period */
struct PBA_PlanPeriod {
    1: PBA_planPeriodId id,
    2: i16     period,
    3: PBA_periodType type,
    4: bool    isTrial,
    5: double  setupFee,
    6: double  subscriptionFee,
    7: double  renewalFee,
    8: double  transferFee,
    9: double  nonRefundableAmount,
    10: i16    refundPeriod,
    11: bool   isEnabled,
    12: i16    numberOfPeriods,
    13: string feeText,
}

/* Resource */
struct PBA_Resource {
    1: PBA_resourceId id,
    2: string name,
    3: string description,
    4: string unit,
}

/* Resource usage */
struct PBA_ResourceUsage {
    1: PBA_resourceId id,
    2: i32 rateId,
    3: string name,
    4: string status,
    5: double includedAmount,
    6: double additionalAmount,
    7: double usedAmount,
    8: double orderedAmount,
    9: string unit,
    10: double setupFee,
    11: double recurringFee,
    12: double overuseFee,
}

/* Payment method */
struct PBA_PaymentMethod {
    1: PBA_paymentMethodId id,
    2: PBA_payType type,

    3: optional PBA_paySystem paySystem,
    4: optional string ccPartialNumber,  # @secure
    5: optional string ccExpiryDate,
    6: optional string ccHolderName,

    7: optional string bankAccountHolderName,
    8: optional string bankAccountBankNumber,
    9: optional string bankAccountPartialNumber,

    10: bool useForAutoPayments,
}

/* Accounts Receivable document */
struct PBA_arDoc {
    1: PBA_arDocId     id,
    2: string          number,
    3: PBA_arDocType   type,
    4: PBA_arDocStatus status,
    5: double          total,
    6: double          balance,
    7: double          available,
    8: UnixTime        date,
    9: UnixTime        dueDate,
    10: string         description,
}

/* Return value from Billing.getAccountDetails */
struct PBA_accountDetails {
    1: PBA_accountId id,
    2: string        name, # @utf8
    3: PBA_Address   address,
    4: PBA_Contact   contact,
    5: UnixTime      creationDate,
}

/* A configured country for the vendor */
struct PBA_Country {
    1: string countryId,
    2: string name,
    3: optional string zipCodeRegex, # Default is '^(.){0,10}$' if not specified
    4: string countryCode,
    5: bool   needAreaCode,
}

/*
 *      EXCEPTIONS
 *
 */


/*
    At least one of the arguments passed was invalid.

    @param message The text of the error
    @param argument The name of the argument that was invalid
*/
exception InvalidArguments {
    1: string message, # @utf8
    2: string argument
}

/*
    The billing failed
*/
exception BillingFailed {
    1: string message # @utf8
}

/*
 *  Service: Common
 */

/*
    Response to Common.healthCheck
*/

struct HealthCheckResponse {
    1: UnixTime start,     # Start time of the provider process
    2: string hostname,    # Hostname where provider resides
    3: string loadAverage, # Average load of system
}

/*
    Response to Common.ping
    
*/
struct PingResponse {
    1: UnixTime start,  # Time
    2: string pong,     # Ping response.
    3: string echo,     # @utf8 Simple payload, if passed.
}

service Common {
    /*
        Provide a health check for each server
        @role internal
    */
    HealthCheckResponse healthCheck (),

    /*
        Provide a ping facility for each service
        @role customer
    */
    PingResponse ping (
        1: string echo, # @utf8 @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Create an object setting
        @role customer
    */
    ObjectSettingId createObjectSetting (
        1: ObjectSettingContext context,
        2: ObjectId             objectId,
        3: SettingId            settingId,
        4: SettingValue         value,
    ) throws (1: InvalidArguments ouch),

    /*
        Clear an object setting
        @role customer
    */
    void clearObjectSetting (
        1: ObjectSettingId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Update an object setting value
        @role customer
    */
    void updateObjectSetting (
        1: ObjectSettingId id,
        2: SettingValue value,
    ) throws (1: InvalidArguments ouch),

    /*
        Get all the object settings, and catalog ids, for an object
        @role customer
    */
    ComputedObjectSettings getObjectSettings (
        1: ObjectSettingContext context,
        2: ObjectId             objectId,
        3: list<SettingClass>   limitClasses, # Explicitly state which classes we want ('PHP', 'LB', 'Customer') @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Get the catalog
        @role customer
    */
    list<SettingCatalog> getSettingCatalog (
    ) throws (1: InvalidArguments ouch),
}
/*
    Customer methods.

    @role customer
*/
service Customer extends Common {
    /*
        Control Panel wizard
    */
    void CP_Wizard (
        1: CustomerId     customerId,
        2: SiteName       siteName,
        3: Hostname       siteHostname,
        4: ContainerName  containerName,
        8: ContainerTypeId containerType,
        6: list<EnvironmentName> environmentNames,
        7: list<SiteAlias> aliasNames,                 # @optional
    ) throws (1: InvalidArguments ouch),
    
    /*
        Create a Customer

        @role internal
    */
    CustomerId create (
        1: CustomerId id, # @optional
        2: CustomerName name,
        3: CustomerType type,
        4: EmailAddress email,
        5: CustomerUsername username,
        6: string password, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Create a cancellation request for a customer
    */
    void requestCancellation (
        1: CustomerId id,
        2: string reason,
    ) throws (1: InvalidArguments ouch),

    /*
        Create an API Key for the customer
    */
    APIKey createKey (
        1: CustomerId id,
        2: APIKeyType type, # @optional @role internal
    ) throws (1: InvalidArguments ouch),

    /*
        Revoke an API Key for the customer
    */
    void revokeKey (
        1: APIKeyId id,
    ) throws (1: InvalidArguments ouch),

    /*
        List all customer Keys
    */
    APIKeys getKeys (
        1: CustomerId id,
        2: APIKeyType type, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Associate an ACL with the key
    */
    APIKeyACL createKeyACL (
        1: APIKeyId id,
        2: IPAddress address,
        3: CIDRMask cidr,
    ) throws (1: InvalidArguments ouch),

    /*
        Update a field on the ACL
    */
    APIKeyACL updateKeyACL (
        1: APIKeyACLId id,
        2: IPAddress address, # @optional
        3: CIDRMask cidr,     # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Delete a key ACL
    */
    void deleteKeyACL (
        1: APIKeyACLId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Add role to customer

        @role internal
    */
    void assignRole (
        1: CustomerId id,
        2: Role role,
    ) throws (1: InvalidArguments ouch),

    /*
        Remove role from customer

        @role internal
    */
    void removeRole (
        1: CustomerId id,
        2: Role role,
    ) throws (1: InvalidArguments ouch),

    /*
        List all customer roles
    */
    list<Role> listRoles (
        1: CustomerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Get Customer Username
    */
    CustomerUsername getUsername (
        1: CustomerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Change the customer password
    */
    void changePassword (
        1: CustomerId id,
        2: string password,  # @validate length 1-
    ) throws (1: InvalidArguments ouch),

    /*
        Change the customer email address
    */
    void changeEmail (
        1: CustomerId id,
        2: EmailAddress email,
    ) throws (1: InvalidArguments ouch),

    /*
        Destroy a Customer

        @role internal
    */
    void destroy (
        1: CustomerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Set a list of settings on the Customer

        @param id           the ID of the Customer
        @param settings     a list of the settings
    */
    void setSettings (
        1: CustomerId id,
        2: SettingList settings,
    ) throws (1: InvalidArguments ouch),

    /*
        Get all the settings associated with the Customer

        @param id   the ID of the Customer
    */
    SettingList getSettings (1: CustomerId id) throws (1: InvalidArguments ouch),

    /*
        Find a Customer

        @role internal

        @return List of every CustomerId which matches the criteria
    */
    list<CustomerId> find (
        1: CustomerName name,         # @optional
        2: CustomerType type,         # @optional
        3: EmailAddress email,        # @optional
        4: CustomerUsername username, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Add address to the Customer
    */
    IPAddress addIpAddress (
        1: CustomerId id,
        2: IPAddress address, # @optional @role internal
    ) throws (1: InvalidArguments ouch),

    /*
        Get Addresses associated with Customer
    */
    list<IPAddress> getIpAddresses (
        1: CustomerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Get address details for a Customer
    */
    list<IPAddressDetails> getDetailedIpAddresses (
        1: CustomerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Free an Address from the customer
    */
    void freeIpAddress (
        1: CustomerId id,
        2: IPAddress address,
    ) throws (1: InvalidArguments ouch),

    /*
        Create a Customer-controlled FTP user
    */
    FTPUser createFTPUser (
        1: CustomerId       customerId,
        2: CustomerName     name,
        3: CustomerUsername username,
        4: string           password,
        5: string           relativeRoot,  # @utf8
        6: FTPUserType      type,
        7: SiteId           siteId,        # @optional
        8: EnvironmentId    environmentId, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        List FTP users
    */
    list<FTPUser> listFTPUsers (
        1: CustomerId    id,
        7: SiteId        siteId,        # @optional
        8: EnvironmentId environmentId, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Update an FTP user
    */
    void updateFTPUser (
        1: FTPUserId        id,
        2: CustomerName     name,         # @optional
        3: CustomerUsername username,     # @optional
        4: string           password,     # @optional
        5: string           relativeRoot, # @utf8 @optional
        6: FTPUserType      type,         # @optional
        7: SiteId           siteId,        # @optional
        8: EnvironmentId    environmentId, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Delete an FTP user
    */
    void destroyFTPUser (
        1: FTPUserId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Fetch the latest billable bandwidth amount
    */
    ResourceHistoricalUsage currentBillableBandwidth (
        1: CustomerId customerId,
    ) throws (1: InvalidArguments ouch),

    /*
        Fetch all the notices associated with the customer (or global)
    */
    list<CustomerNotice> listNotices (
        1: CustomerId customerId,
        2: UnixTime since,       # Ignore notices that were created or updated before this time @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Set the acknowledged flag of a customer notice
    */
    void acknowledgeNotice (
        1: CustomerNoticeId noticeId
    ) throws (1: InvalidArguments ouch),
}

/*
    Container methods.

    @role customer
*/
service Container extends Common {
    /*
        Order a Container
    */
    ContainerDetails order (
        1: CustomerId     customerId,
        2: ContainerName  name,
        7: ContainerTypeId type,
        4: ContainerSize  size,    # @optional
        5: PBA_paymentMethodId paymentMethodId, # @optional
        6: string         promoCode, # @optional,
    ) throws (
        1: InvalidArguments ouch,
        2: BillingFailed    noBill
    ),

    /*
        Create a Container
        @role internal
    */
    ContainerDetails create (
        1: CustomerId customerId,
        2: ContainerId id,        # the id of the container @role internal @optional
        3: ContainerUuid uuid,    # the uuid of the container @role internal @optional
        4: IPAddress address,     # the address @role internal @optional
        5: ContainerName name,
        6: ContainerOS os,
        9: ContainerTypeId type,
        8: ContainerSize size,    # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Register a Container. Runs on container startup and informs provisioning platform
        if various actions had to be taken to get the container to a known state.

        @param id       Id of the container
        @param mount    True: create mount False: mount created.
        @param uuid     True: updated uuid False: uuid okay.
        @param puppet   True: updated puppet False: puppet okay.
        @param repo     True; updated repo False: repo okay.
        @role internal
    */
    void registerReport (
        1: ContainerId id,        # @optional
        2: bool mount,            # @optional
        3: bool uuid,             # @optional
        4: bool puppet,           # @optional
        5: bool repo,             # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Orders a resource change for a Container
    */
    void orderResourceChange (
        1: ContainerId id,
        2: ContainerSize size
    ) throws (
        1: InvalidArguments ouch,
        2: BillingFailed    noBill
    ),

    /*
        Set resource allocation for the Container.

        @param  id     ID of the Container you wish to destroy
        @param  size   Resources to be allocated to the Container
        @role internal
    */
    void setResources (
        1: ContainerId id,
        2: ContainerSize size
    ) throws (1: InvalidArguments ouch),

    /*
        Delete a Container

        @param  id     ID of the Container you wish to destroy
    */
    void destroy (1: ContainerId id) throws (1: InvalidArguments ouch),

    /*
        Rename a Container
    */
    void rename (
        1: ContainerId id,
        2: ContainerName name,
    ) throws (1: InvalidArguments ouch),

    /*
        Start a Container

        @param  id     ID of the Container you wish to start
    */
    void start (1: ContainerId id) throws (1: InvalidArguments ouch),

    /*
        Stop a Container

        @param  id     ID of the Container you wish to stop
    */
    void stop (1: ContainerId id) throws (1: InvalidArguments ouch),

    /*
        Reboot a Container

        @param  id     ID of the Container you wish to reboot
    */
    void reboot (1: ContainerId id) throws (1: InvalidArguments ouch),

    /*
        Search for a container.

        @param uuid       UUID of the container to find
        @param address    IP address belonging to the container
        @param customerId ID of a customer

        @return a list of ContainerId

    */
    list<ContainerDetails> find (
        1: ContainerUuid uuid,      # @optional
        2: IPAddress address,       # @optional
        3: CustomerId customerId,   # @optional
        4: ContainerId id,          # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Get a UUID for a Container.

        @param id
    */
    ContainerUuid getUuid (
        1: ContainerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Set a UUID for a Container.

        @param id
        @param uuid

        @role  internal
    */
    void setUuid (
        1: ContainerId id,
        2: ContainerUuid uuid,
    ) throws (1: InvalidArguments ouch),

    /*
        Set a list of settings on the Container

        @param id the ID of the Container
        @param settings a list of the settings
    */
    void setSettings (
        1: ContainerId id,
        2: SettingList settings,
    ) throws (1: InvalidArguments ouch),

    /*
        Get the current resource usage
    */
    ResourceCurrentUsage getCurrentResourceUsage (
        1: ContainerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Get a list of usage data for a given interval
        The creation time of the container must not come after startTime + intervalTime or errors may occur
    */
    list<ResourceHistoricalUsage> getHistoricalResourceUsage (
        1: ContainerId id,
        2: UnixTime startTime,
        3: UnixTime endTime,
        4: i32      intervalTime,         # The time in seconds between each record
        5: list<ResourceUsageType> types, # A list of which resource usage types you'd like data for
    ) throws (1: InvalidArguments ouch),

    /*
        Returns a list of Environments that this container is serving. Returns list<ContainerEnvironmentDetails>
    */
    list<ContainerEnvironmentDetails> listEnvironments (
        1: ContainerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Get a process table graph for a container over a period of time
    */
    ProcessTableGraph getProcessTableGraph (
        1: ContainerId id,
        2: UnixTime    startTime,
        3: UnixTime    endTime,
        4: i32         intervalTime,  # The time in seconds between each record
        5: i16         limit,         # Limit the number of processes returned @optional
        6: list<ProcessTableMetric> metrics, # What metrics are we graphing
        7: map<ProcessTableMetric,i32> thresholds, # Require all processes that are returned to have some values above this threshold.  Units are contextual to the metric. @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Get a process table for a moment in time
    */
    ProcessTable getProcessTable (
        1: ContainerId id,
        2: UnixTime time,
    ) throws (1: InvalidArguments ouch),

    /*
        List all the available types to containers
    */
    list<ContainerType> listTypes (
    ) throws (1: InvalidArguments ouch),

    /*
        List all the available upgrades for a container
    */
    list<ContainerType> listConvertTypes (
        1: ContainerTypeId typeId
    ) throws (1: InvalidArguments ouch),

    /*
        Convert a container to a different type, if possible
    */
    void convertType (
        1: ContainerId id,
        2: ContainerTypeId typeId,
    ) throws (1: InvalidArguments ouch),

    /*
        List all the available commands that can be run against a container
    */
    list<ContainerCommand> listCommands (
        1: ContainerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Run a command against a container
    */
    ContainerCommandResponse runCommand (
        1: ContainerId id,
        2: ContainerCommandId commandId, # @optional
        3: string commandName,           # @optional
        4: list<ContainerCommandArgument> arguments,
    ) throws (1: InvalidArguments ouch),

    /*
        List container status changes
    */
    list<ContainerHistoricalStatus> getHistoricalStatus (
        1: ContainerId id,
        2: UnixTime    startTime, # @optional
        3: UnixTime    endTime,   # @optional
        4: i16         limit,                          # Limit the number of records returned @optional
        5: list<ContainerHistoricalStatusName> status, # Limit only to these status @optional
        6: list<ContainerHistoricalTransitionName> transitions, # Limit only to these transitions @optional
    ) throws (1: InvalidArguments ouch),

    /*
        List container status changes
    */
    list<ContainerHistoricalAlert> getHistoricalAlerts (
        1: ContainerId id,
        2: UnixTime    startTime, # @optional
        3: UnixTime    endTime,   # @optional
        4: i16         limit,                              # Limit the number of records returned @optional
        5: list<ContainerHistoricalAlertCounter> counters, # Limit only to these counters @optional
    ) throws (1: InvalidArguments ouch),
}
/*
    Site methods.

    @role customer
*/
service Site extends Common {

    /*
        Create a site.  Note that the hostname must not already be in use or an InvalidArguments will be thrown.

        @param name           a friendly name for the site (for your use) 
        @param hostname       a fully qualified domain name (fqdn)
        @param environmentName  the name of the Environment to create
        @param address        the ip address that the site should be bound to
        @param ssl            reserve SSL for the SiteAddress
        @param containers     a list of container ids that the site environment will be configured on
        @param createDNS      if true, DNS records will be created for the new site and aliases

        @return the newly created id of the site
    */
    SiteId create (
        1: CustomerId customerId,
        2: SiteName name,
        3: Hostname hostname,
        4: EnvironmentName environmentName, 
        9: ContainerTypeId environmentType,
        5: IPAddress address,           # @optional
        6: bool ssl,                    # @optional
        7: list<ContainerId> containers,
        8: list<SiteAlias> aliases,     # @optional
        10: bool createDNS,             # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Delete a Site

        @param id the id of the site
    */
    void destroy (1: SiteId id) throws (1: InvalidArguments ouch),

    /*
        Update the site details.  Provide 'name' and/or 'hostname'.  Note that, if changing the hostname, the new hostname must not already be in use or an InvalidArguments will be thrown.
    */
    void update (
        1: SiteId id,
        2: SiteName name,     # @optional
        3: Hostname hostname, # @optional
        4: bool updateDNS,    # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Search for a site.
    */
    list<SiteDetails> find (
        1: CustomerId customerId, # @optional
        2: SiteName name,         # @optional
        3: Hostname hostname,     # @optional
        4: IPAddress address,     # @optional
        5: SiteId id,             # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        get all the settings associated with the site

        @param id   the id of the site
    */

    SettingList getSettings (1: SiteId id) throws (1: InvalidArguments ouch),

    /*
        set a list of settings on the site

        @param id           the id of the site
        @param settings     a list of the settings
    */
        
    void setSettings (
        1: SiteId id,
        2: SettingList settings,
    ) throws (1: InvalidArguments ouch),

    /*
        get all aliases associated with the site

        @param id       the id of the site

        @return         a list of sitealiases
    */
    SiteAliasList getAliases (1: SiteId id) throws (1: InvalidArguments ouch),

    /*
        Add an alias to a site.  Note that the alias must not already be in use or an InvalidArguments will be thrown.

        @param id           the id of the site to which you want to add an alias
        @param alias        the new alias (fqdn) for the site
        @param aliases      (optional) list of aliases
    */
    list<SiteAliasId> addAlias (
        1: SiteId id,
        2: SiteAlias alias,         # @optional
        4: list<SiteAlias> aliases, # @optional
        3: bool createDNS,  # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Remove an alias from a site

        @param  id          the id of the alias to destroy
    */
    void destroyAlias (
        1: SiteAliasId id,
    ) throws (1: InvalidArguments ouch),

    /*
        fetch the address for this site

        @param id
    */
    IPAddress getAddress (
        1: SiteId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Associate an address with the site
        @param address If left empty, and if not createNewAddress, it will default to the currently assigned address
    */
    IPAddress updateAddress (
        1: SiteId id,
        2: IPAddress address,     # @optional
        3: bool isSSLReserved,    # @optional
        4: bool createNewAddress, # @optional
        5: bool updateDNS,        # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Assign an SSL certificate with the site.
        If there was a previous certificate, it will be replace.
        @param certificateId If left blank, unassigns the certificate
    */
    void assignCertificate (
        1: SiteId        siteId,
        2: CertificateId certificateId, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Fetch the current site status
    */
    SiteLoadBalancerStatus getLoadBalancerStatus (
        1: SiteId siteId,
        2: UnixTime time, # If present, will search for closest record to this time (backwards); otherwise, defaults to latest status @optional
    ) throws (1: InvalidArguments ouch),
}
/*
    Environment methods.
    @role customer
*/
service Environment extends Common {
    /*
        create an environment for a site

        @param  id              the id of the site
        @param  name            the name of the environment
        @param  containers      a list of containerids to configure the site environment on

        @return                 the id of the newly created environment
    */
    EnvironmentId create (
        1: SiteId id,
        2: EnvironmentName name,
        3: list<ContainerId> containers,
        4: ContainerTypeId type,
    ) throws (1: InvalidArguments ouch),

    /*
        Create a new environment, cloning the settings and files of an existing environment
    */
    EnvironmentId clone (
        1: EnvironmentId source,
        2: EnvironmentName name,
        3: list<ContainerId> containers,
        4: ContainerTypeId type,
    ) throws (1: InvalidArguments ouch),

    /*
        Delete an environment

        @param id  the id of a the environment you wish to destroy
    */
    void destroy (
        1: EnvironmentId id
    ) throws (1: InvalidArguments ouch),

    /*
        enable an environment
    */
    void enable (1: EnvironmentId id) throws (1: InvalidArguments ouch),

    /*
        disable an environment
    */
    void disable (1: EnvironmentId id) throws (1: InvalidArguments ouch),

    /*
        Search for an environment
    */
    list<EnvironmentDetails> find (
        1: CustomerId    customerId,  # @optional
        2: SiteId        siteId,      # @optional
        3: ContainerId   containerId, # @optional
        4: EnvironmentId id,          # @optional
        5: EnvironmentName name,      # @optional
        6: bool isEnabled,            # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        fetch the address for this environment
    */
    IPAddress getAddress (
        1: EnvironmentId id
    ) throws (1: InvalidArguments ouch),

    /*
        set an environment 'live'

        @param id
    */
    void setLive (
        1: EnvironmentId id
    ) throws (1: InvalidArguments ouch),

    /*
        list the history of live environments (all history, or just an interval)

        @param id
        @param interval
    */
    LiveEnvironmentHistory liveHistory (
        1: EnvironmentId id,
        2: TimeInterval interval, # @optional
    ) throws (1: InvalidArguments ouch),

    /* 
        Make a container the master for this environment.
        If another container is already the master, this will replace that.
    */
    void setContainerMaster (
        1: EnvironmentId environmentId,
        2: ContainerId   containerId,
    ) throws (1: InvalidArguments ouch),

    /*
        get all the settings associated with the environment

        @param id   the id of the environment
    */
    SettingList getSettings (
        1: EnvironmentId id
    ) throws (1: InvalidArguments ouch),

    /*
        set a list of settings on the environment

        @param id               the id of the environment
        @param settings         a list of the settings
    */
    void setSettings (
        1: EnvironmentId id,
        2: SettingList settings,
    ) throws (1: InvalidArguments ouch),

    /*
        add a database to an environment

        @param id    id of the environment 
        @param DatabaseId       id of the database to associate with this environment

    */
    void addDatabase (
        1: EnvironmentId id,
        2: DatabaseId databaseId,
    ) throws (1: InvalidArguments ouch),

    /*
        remove a database from an environment

        @param id    id of the environment 
        @param DatabaseId       id of the database to remove from this environment

    */
    void removeDatabase (
        1: EnvironmentId id,
        2: DatabaseId databaseId,
    ) throws (1: InvalidArguments ouch),

    /*
        add containers to an environment

        @param id
        @param containers
    */
    void addContainers (
        1: EnvironmentId id,
        2: list<ContainerId> containers,
    ) throws (1: InvalidArguments ouch),

    /*
        List containers in this Environment

        @param id
    */
    list<ContainerId> listContainers (
        1: EnvironmentId id,
    ) throws (1: InvalidArguments ouch),

    /*
        remove containers to an environment

        @param id
        @param containers
    */
    void removeContainers (
        1: EnvironmentId id,
        2: list<ContainerId> containers,
    ) throws (1: InvalidArguments ouch),

    /*
        Get all aliases associated with the environment

        @return         a list of sitealiases
    */
    EnvironmentAliasList getAliases (1: EnvironmentId id) throws (1: InvalidArguments ouch),

    /*
        add an alias to a site environment

        @param alias        the new alias (fqdn) for the site environment
        @param aliases      (optional) list of aliases
    */
    list<EnvironmentAliasId> addAlias (
        1: EnvironmentId id,
        2: EnvironmentAlias alias,
        4: list<EnvironmentAlias> aliases, # @optional
        3: bool createDNS,                 # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Remove an alias from a site environment

        @param  id          the id of the alias to destroy
    */
    void destroyAlias (
        1: EnvironmentAliasId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Restart services on containers participating in this environment

        @param graceful     execute a graceful restart of services (if supported)
        @param configtest   execute a conditional restart based on clean configuration
    */
    list<ContainerCommandResponse> restartServices (
        1: EnvironmentId id,
        2: bool graceful,                  # @optional
        3: bool configtest,                # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Check service configuration for this Environment.

    */
    list<ContainerCommandResponse> checkServiceConfig (
        1: EnvironmentId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Remove an alias from a site environment

        @param  id          the id of the alias to destroy
    */
    void destroyAlias (
        1: EnvironmentAliasId id,
    ) throws (1: InvalidArguments ouch),
}

# vim:ts=4:sw=4:expandtab:cindent:syntax=thrift
/*
    Load Balancer methods.

    @role internal
*/
service Loadbalancer extends Common {
    /*
        Reconfigure Site and/or Environment

        @param siteId           Pass siteId if you want to reconfigure a Site
        @param environmentId    Pass environmentId if you want to reconfigure an Environment
        @param reload           Default behavior is to reload config on every reconfigure
    */
    void reconfigure (
        1: SiteId siteId,               # @optional
        2: EnvironmentId environmentId, # @optional
        3: bool reload                  # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Destroy a site or Environment

        @param siteId
        @param id
    */
    void destroy (
        1: SiteId siteId,               # @optional
        2: EnvironmentId environmentId, # @optional
        3: bool reload                  # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Reload

        @param now      True for reload, False for NOOP

    */
    void reload (
        1: bool now,               # @optional
    ) throws (1: InvalidArguments ouch),
}
/*
    Puppet methods.
*/
service Puppet extends Common {
    /*
        Update puppet configuration for a Customer

        @param  id      ID for the customer to provision puppet for
        @role internal
    */
    void updateCustomer (
        1: CustomerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Update puppet configuration for a Container

        @param  id  ID for the container to provision puppet for
        @role internal
    */
    void updateContainer (
        1: ContainerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Destroy container

        @param id
        @role internal
    */
    void destroyContainer (
        1: ContainerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Destroy customer

        @param id
        @role internal
    */
    void destroyCustomer (
        1: CustomerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Retrieve container manifest.

        @param id
        @role internal
    */
    ContainerManifest getContainerManifest (
        1: ContainerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Run puppet for a customer (all containers) or a list of containers.
        @role customer
    */
    void deploy(
        1: CustomerId customerId,        # @optional
        2: list<ContainerId> containers, # @optional
        3: list<SiteId> siteIds,         # @optional
        4: list<EnvironmentId> environmentIds, # @optional
    ) throws (1: InvalidArguments ouch),

}
/*
    Database methods.

    @role customer
*/
service Database extends Common {
    /*
        Create a database and an initial database user
        You may use any characters to describe the database (up to 59 in length).  This will be normalized (spaces removed, etc.) but the original name will be preserved as a friendly name.
        The normalized name for the database will be returned in the DatabaseDetails.
        If performed on a PostgreSQL database, the username and name must be the same value.
    */
    DatabaseCreateResult create (
        1: DatabaseType     type,
        2: CustomerId       customerId,
        6: DatabaseName     name,          # The four character customer digest and a '_' will be prefixed to this @validate length 1-59
        7: DatabaseUser     username,      # The four character customer digest and a '_' will be prefixed to this @validate length 1-11
        8: DatabasePassword password,      # The inital password for the user created @optional
        5: bool             storePassword, # Store the password so it can be retrieved @optional
        9: DatabaseUserType userType,      # Defaults to ReadWrite @optional
        10: list<Hostname>   hostsAllow,   # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Change the name for a Database
        You may use any characters to describe the database (up to 59 in length).  This will be normalized (spaces removed, etc.) but the original name will be preserved as a friendly name.
        The new normalized name for the database will be returned in the DatabaseDetails.
        If performed on a PostgreSQL database, the username will also be renamed.
    */
    DatabaseDetails rename (
        1: DatabaseId   id,
        3: DatabaseName name,   # The four character customer digest and a '_' will be prefixed to this @validate length 1-59
    ) throws (1: InvalidArguments ouch),

    /*
        Clone a database to a new database and an initial database user
        If performed on a PostgreSQL database, the username and name must be the same value.
    */
    DatabaseCreateResult clone (
        1: DatabaseId       id,
        5: DatabaseUser     username,      # The four character customer digest and a '_' will be prefixed to this @validate length 1-11
        6: DatabaseName     name,          # The four character customer digest and a '_' will be prefixed to this @validate length 1-59
        7: DatabasePassword password,      # The inital password for the user created @optional
        4: bool             storePassword, # Store the password so it can be retrieved @optional
        8: DatabaseUserType userType,      # Defaults to ReadWrite @optional
        9: list<Hostname>   hostsAllow,    # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        List details of one or many Databases. (always returns list)

        @param      customerId      List all databases for this customer.
        @param      databaseId      List details for this database

        @returns    list<DatabaseDetails>   Always returns a list of DatabaseDetail records
    */
    list<DatabaseDetails> listDatabases (
        1: CustomerId customerId,   # @optional
        2: DatabaseId databaseId,   # @optional
    ) throws (1: InvalidArguments outch),

    /*
        Delete a Database

        @param  id      DatabaseId of the Database to destroy
        @param  backup  Bool, true will dump the database before delete, false will not.

        @returns    URL     Location of the final backup.
    */
    URL destroy (
        1: DatabaseId id,
        2: bool backup      # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Backup a database

        @param  id  the ID of the Database you wish to backup
    */
    DatabaseBackup backup (
        1: DatabaseId id
    ) throws (1: InvalidArguments ouch),

    /*
        List database backups

        @param  id  the database id.
    */
    list<DatabaseBackup> listBackups (
        1: DatabaseId id
    ) throws (1: InvalidArguments ouch),

    /*
        Destroy a database backup

        @param  databaseId  the database id.
        @param  backupId    the backup id.
    */
    void destroyBackup (
        1: DatabaseId databaseId,
        2: DatabaseBackupId backupId,
    ) throws (1: InvalidArguments ouch),

    /*
        Create a new database user
    */
    DatabaseUserDetails createUser (
        1: DatabaseId       databaseId,
        2: DatabaseUser     username,      # The four character customer digest and a '_' will be prefixed to this @validate length 1-11
        3: DatabasePassword password,      # If not provided, a random password will be created @optional
        4: bool             storePassword, # Store the password so it can be retrieved @optional
        5: DatabaseUserType userType,      # Defaults to ReadWrite @optional
        6: list<Hostname>   hostsAllow,    # @optional

        # PgSQL specific options
        7: bool             pgDatabaseOwner, # For a PostgreSQL database, this will make the new user the owner of the database @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Update one or more aspects of a database user
    */
    DatabaseUserDetails updateUser (
        1: DatabaseUserId   id,
        2: DatabasePassword password,       # @optional
        3: bool             storePassword,  # @optional
        4: DatabaseUserType userType,       # @optional
        5: list<Hostname>   hostsAllow,     # If present, replaces the previous values @optional

        # PgSQL specific options
        6: bool             pgDatabaseOwner, # For a PostgreSQL database, this will make the user the owner of the database @optional
    ) throws (1: InvalidArguments ouch),

    /*
        List all the users on a database
    */
    list<DatabaseUserDetails> listUsers (
        1: DatabaseId databaseId
    ) throws (1: InvalidArguments ouch),

    /*
        Delete a user on a database
    */
    void destroyUser (
        1: DatabaseUserId id
    ) throws (1: InvalidArguments ouch),

    /*
        Retrieve slow logs for a given database and range
    */
    list<DatabaseSlowLog> getSlowLogs (
        1: DatabaseId     databaseId,
        2: DatabaseUserId userId,    # @optional
        3: UnixTime       startTime, # @optional
        4: UnixTime       endTime,   # @optional
        5: i16            limit,     # @optional
    ) throws (1: InvalidArguments ouch),
}

/*
    Return value from DatabaseInstance.listGrants
    @role internal
*/
struct DatabaseInstanceGrant {
    1: string userName,
    2: string databaseName,

    # MySQL specific options
    3: optional bool           mySelectOnly,
    4: optional list<Hostname> myHostsAllow,

    # PgSQL specific options
    5: optional list<DatabasePostgreACL> pgHostsAllow,
    6: optional bool pgDatabaseOwner,
}

/*
    Service running on a single database server instance
    (MySQL or PostgreSQL, master or replica)

    @role internal
*/
service DatabaseInstance extends Common {

    /** Database Operations **/

    /*
        Create a database
    */
    void createDatabase (
        1: string name,
    ) throws (1: InvalidArguments ouch),

    /*
        List all the databases or just those matching a PCRE
        Currently unimplemented
    */
    list<string> listDatabases (
        1: string matching, # Perl-compatible RegEx @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Rename a database
    */
    void renameDatabase (
        1: string name,
        2: string newName,
    ) throws (1: InvalidArguments ouch),

    /*
        Drop a database
    */
    void destroyDatabase (
        1: string name,
    ) throws (1: InvalidArguments ouch),

    /*
        Clone a database
    */
    void cloneDatabase (
        1: string source, # Copy the contents of this database...
        2: string target, # ...to this one
    ) throws (1: InvalidArguments ouch),

    /*
        Create a dump file of the database
    */
    DatabaseBackup createDatabaseBackup (
        1: string name,
    ) throws (1: InvalidArguments ouch),

    /*
        List all the database backups
    */
    list<DatabaseBackup> listDatabaseBackups (
        1: string name,
    ) throws (1: InvalidArguments ouch),

    /*
        Delete a database backup
    */
    void destroyDatabaseBackup (
        1: DatabaseBackupId id
    ) throws (1: InvalidArguments ouch),

    /** User Operations **/

    /*
        Create a user
    */
    void createUser (
        1: string name,
        2: string password,

        # MySQL specific options
        3: i16 myMaxQueriesPerHour,     # @optional
        4: i16 myMaxUpdatesPerHour,     # @optional
        5: i16 myMaxConnectionsPerHour, # @optional
        6: i16 myMaxUserConnections,    # @optional
    ) throws (1: InvalidArguments ouch),
    
    /*
        List all the users or just those matching a MySQL regex
    */
    list<string> listUsers (
        1: string matching, # MySQL RegEx @optional
    ) throws (1: InvalidArguments ouch),
     
    /*
        Update a user
    */
    void updateUser (
        1: string name,
        2: string password,             # @optional

        # MySQL specific options
        3: i16 myMaxQueriesPerHour,     # @optional
        4: i16 myMaxUpdatesPerHour,     # @optional
        5: i16 myMaxConnectionsPerHour, # @optional
        6: i16 myMaxUserConnections,    # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Delete a user
    */
    void destroyUser (
        1: string name,
    ) throws (1: InvalidArguments ouch),

    /** Grant Operations **/

    /*
        Grant a user access to a database
    */
    void createGrant (
        1: string userName,
        2: string databaseName,

        # MySQL specific options
        3: bool           mySelectOnly, # @optional
        4: list<Hostname> myHostsAllow, # @optional

        # PgSQL specific options
        5: list<DatabasePostgreACL> pgHostsAllow, # @optional
        6: bool pgDatabaseOwner,                  # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        List all user access to a database
    */
    list<DatabaseInstanceGrant> listGrants (
        1: string databaseName
    ) throws (1: InvalidArguments ouch),

    /*
        Update grant for a user on a database
    */
    void updateGrant (
        1: string userName,
        2: string databaseName,

        # MySQL specific options
        3: bool           mySelectOnly, # @optional
        4: list<Hostname> myHostsAllow, # @optional

        # PgSQL specific options
        5: list<DatabasePostgreACL> pgHostsAllow, # @optional
        6: bool pgDatabaseOwner,                  # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Revoke user access to a database
    */
    void destroyGrant (
        1: string userName,
        2: string databaseName,
    ) throws (1: InvalidArguments ouch),
}

/*
    DNS methods.
    @role customer
*/
service DNS extends Common {

    /*
        Create a new domain name.  Necessary before creating records.
        The 'name' must be globally unique, so only use fully qualified domain names.
        If the domain already exists (created by you or someone else), an InvalidArguments exception will be raised on the 'name' argument.
    */
    DomainDetails createDomain (
        1: CustomerId customerId, # @optional
        2: DomainName name,
    ) throws (1: InvalidArguments ouch),

    /*
        List domains that match optional criteria.
    */
    list<DomainDetails> listDomains (
        1: CustomerId customerId,  # @optional
        2: DomainName name,        # @optional
        3: DomainId   domainId,    # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Destory a domain and all its related records.
        Provide 'id' or 'name' to refer to the domain, but not both.
    */
    void destroyDomain (
        1: DomainId   id,    # @optional
        2: DomainName name,  # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Create a domain record on a previously existing domain.
        If the record already exists, no error will be thrown.
        Provide 'domainId' or 'domainName' to refer to the domain, but not both.
    */
    DomainRecordDetails createRecord (
        1: DomainId              domainId,   # @optional
        2: DomainName            domainName, # @optional
        3: DomainRecordName      name,
        4: DomainRecordType      type,
        5: DomainRecordContent   content,
        6: DomainRecordTTL       ttl,        # @optional
        7: DomainRecordPriority  priority    # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Update a domain record by its id.
    */
    DomainRecordDetails updateRecord (
        1: DomainRecordId        id,
        2: DomainRecordName      name,     # @optional
        3: DomainRecordType      type,     # @optional
        4: DomainRecordContent   content,  # @optional
        5: DomainRecordTTL       ttl,      # @optional
        6: DomainRecordPriority  priority  # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        List all records matching optional criteria.  Must provide a domain.
        Provide 'domainId' or 'domainName' to refer to the domain, but not both.
    */
    list<DomainRecordDetails> listRecords (
        1: DomainId              domainId,   # @optional
        2: DomainName            domainName, # @optional
        3: DomainRecordName      name,       # @optional
        4: DomainRecordType      type,       # @optional
        5: DomainRecordContent   content,    # @optional
        6: DomainRecordTTL       ttl,        # @optional
        7: DomainRecordPriority  priority    # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Delete a single domain record by id.
    */
    void destroyRecord (
        1: DomainRecordId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Delete all records by DomainName and DomainRecordName
    */
    void destroyRecordsByName (
        1: DomainName domain,
        2: DomainRecordName name,
    ) throws (1: InvalidArguments ouch),
}
typedef i32 StorageFileId

// @validate regex /^[0-9a-f]{32}$/
typedef string HashMD5Hex

/*
   Representation of a single file that is associated with a container
*/
struct StorageFile {
    1: optional StorageFileId id,
    2: ContainerId containerId,
    3: string path, # @utf8
    4: i32 uid,
    5: i32 gid,
    6: i32 mode,
    7: UnixTime mtime,
    8: i32 size,
    9: HashMD5Hex hash,
    10: optional string content # @utf8
}

/*
    Storage methods.
*/
service Storage extends Common {
    /*
        Check storage status for a Container

        @param id      ID of the Container to destroy storage for

        @role  internal
    */
    ContainerStorage checkContainerStorage (
        1: ContainerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Create storage for a container

        @param id      ID of the Container to create storage for

        @role  internal
    */
    void createContainerStorage (
        1: ContainerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Destroy storage for a container

        @param id      ID of the Container to destroy storage for

        @role  internal
    */
    void destroyContainerStorage (
        1: ContainerId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Create storage for an environment

        @param id               ID of the Container to create storage for
        @param environmentId    ID of the Environment to create storage for

        @role  internal
    */
    Path createEnvStorage (
        1: ContainerId id,
        2: EnvironmentId environmentId,
    ) throws (1: InvalidArguments ouch),

    /*
        Move environment storage into deleted/ directory
        @role internal
    */
    void destroyEnvStorage (
        1: ContainerId id,
        2: EnvironmentId environmentId,
    ) throws (1: InvalidArguments ouch),

    /*
        Upon site rename, this call will rename all the site environment directories
        @role internal
    */
    void renameSiteStorage (
        1: SiteId     siteId,
        2: Hostname   oldHostname,
        3: Hostname   newHostname
    ) throws (1: InvalidArguments ouch),

    /*
        Move site storage into deleted/ directory
        @role internal
    */
    void destroySiteStorage (
        1: SiteId siteId,
    ) throws (1: InvalidArguments ouch),

    /*
        sync an environment from one container to a set of containers

        @param  id          EnvironmentId to sync
        @param  source      the source container
        @param  dests       the destination containers

        @role   customer
    */
    void sync (
        1: EnvironmentId id,
        2: ContainerId source,
        3: list<ContainerId> dests,
    ) throws (1: InvalidArguments ouch),

    /*
        Clone the root dir of one environment to another.
        The source and target containers will be the master container for each environment.
        @role customer
    */
    void cloneEnvironment (
        1: EnvironmentId source,
        2: EnvironmentId target,
    ) throws (1: InvalidArguments ouch),

    /*
        Upload a container file to be stored by the provider
        @role internal
        @permitKey Container
    */
    StorageFileId storeFile (
        1: StorageFile file,                    # The 'id' field of this struct should be omitted
        2: StorageFileId replacesStorageFileId, # If present, the indicated file is replaced with this new one @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Find files meta data that matches search criteria.
        The returned StorageFile objects won't include the 'content'
        @role internal
        @permitKey Container
    */
    list<StorageFile> findFiles (
        1: ContainerId containerId, # @optional
        2: string path, # @utf8 @optional
        3: bool pathGlobbing, # If true, '*' matches a single segment and '**' matches multiple segments in 'path' @optional
        4: HashMD5Hex hash, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Fetch a file with content
        @role internal
        @permitKey Container
    */
    StorageFile fetchFile (
        1: StorageFileId id
    ) throws (1: InvalidArguments ouch),

    /*
        Fetch a list of files with content
        @role internal
        @permitKey Container
    */
    list<StorageFile> fetchFiles (
        1: list<StorageFileId> ids
    ) throws (1: InvalidArguments ouch),

    /*
        Delete a file from the provider store
        @role internal
        @permitKey Container
    */
    void deleteFile (
        1: StorageFileId id
    ) throws (1: InvalidArguments ouch),

    /*
        Copy a file from the provider to the container (uses the vzagent filer interface)
        @role internal
    */
    void restoreFileToContainer (
        1: StorageFileId id,
        2: ContainerId destinationContainerId, # If not provided, defaults to the original source of the file @optional
        3: string destinationPath              # If not provided, defaults to the original path of the file @utf8 @optional
    ) throws (1: InvalidArguments ouch),
        
    /*
        Copy a list of files from the provider to the container
        If 'destinationContainerId' is not specified, it's expected that all the files specified have the same original source
        @role internal
    */
    void restoreFilesToContainer (
        1: list<StorageFileId> ids,
        2: ContainerId destinationContainerId, # If not provided, defaults to the original source of the file @optional
        3: string destinationPathPrefix        # If not provided, defaults to '' @utf8 @optional
    ) throws (1: InvalidArguments ouch),
}

# vim:ts=4:sw=4:expandtab:cindent:syntax=thrift
/*
    Certificate Authority methods
    @role customer
*/
service CertificateAuthority extends Common {
    
    /*
        Create a certificate signing request
        @param passphrase If present, will encrypt the private key with this passphrase
    */
    CSR createCSR (
        1: CustomerId         id,
        2: DistinguishedName  subject,
        3: string             passphrase,   # @optional
        4: list<SubjectAltName> altNames,   # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        If you want to generate the CSR yourself, you may, but in order for us
        to generate the certificate, we need it uploaded and assigned an id.
        This is how you would do this.  The private key must not be passphrase encoded.
    */
    CSR uploadCSR (
        1: CustomerId customerId,
        2: PEMString  request,
        3: PEMString  privateKey,
    ) throws (1: InvalidArguments ouch),

    /*
        Retrieve the information of a given CSR id.
        Optionally include the private key in the result.
    */
    CSRMeta getCSR (
        1: CSRId id,
        2: bool  includePrivateKey, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Search for a CSR given certain criteria
        Optionally include the private key in the result.
    */
    list<CSRMeta> findCSR (
        1: CustomerId   customerId,        # @optional
        2: CACommonName commonName,        # @optional
        3: bool         includePrivateKey, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Delete a CSR and it's private key from the database
    */
    void destroyCSR (
        1: CSRId id
    ) throws (1: InvalidArguments ouch),

    /*
        Manually indicate that a CSR domain verification is valid
        @role internal
    */
    void setCSRVerification (
        1: CustomerId customerId,
        2: DomainName domain,
        3: bool isVerified,
    ) throws (1: InvalidArguments ouch),

    /*
        Check if CSR verification is valid yet
    */
    bool checkCSRVerification (
        1: CustomerId customerId,
        2: DomainName domain,
    ) throws (1: InvalidArguments ouch),

    /*
        Create a Stackable CA signed certificate from a CSR
        Indicate how many days you want the cert signed for
    */
    Certificate createCertificate (
        1: CSRId   csrId,
        2: CADays  days,
    ) throws (1: InvalidArguments ouch),

    /*
        If you've purchased your Certificate or created it in some other way,
        you'll need to upload the Certificate to us before it can be installed
        for a Site.
        This is also to be used to upload chained certificates, which you won't
        have the privateKey for for obvious reasons.
        @param csrId Provide the CSR id if we generated the CSR but it was signed elsewhere.  This will bring in the privateKey for you.
    */
    Certificate uploadCertificate (
        1: CustomerId customerId,
        2: PEMString  certificate,
        3: PEMString  privateKey, # @optional
        4: CSRId      csrId,      # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Revoke a certificate by it's id
        You can only revoke certificates that were signed by Stackable
    */
    void revokeCertificate (
        1: CertificateId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Unrevoke a certificate by it's id
        You can only unrevoke certificates that were signed by Stackable
    */
    void unrevokeCertificate (
        1: CertificateId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Delete a certificate.  Also revokes if it's signed by Stackable.
    */
    void destroyCertificate (
        1: CertificateId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Retrieve the information of a given Certificate id
    */
    CertificateMeta getCertificate (
        1: CertificateId id,
        2: bool          includeCSR,        # @optional
        3: bool          includePrivateKey, # @optional
        4: bool          includeChain,      # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Search for a Certificate given certain criteria
        @param validBefore Checks that the validTo of the certificate is after this value @optional
        @param validAfter  Checks that the validTo of the certificate is before this value @optional
    */
    list<CertificateMeta> findCertificate (
        1: CustomerId   customerId,
        2: CACommonName commonName,  # @optional
        3: UnixTime     validBefore, # @optional
        4: UnixTime     validAfter,  # @optional
        5: bool         includeCSR,  # @optional
        6: bool         includePrivateKey, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Request the Stackable CA public key as a PEM-encoded
        x509 certificate.
    */
    PEMString getCAPublicKey (),
}
typedef string CPSessionId
typedef string CPUpdatePasswordId

enum CPDataSortDirection {
    Ascending, Descending
}

enum CPDataSearchOperator {
    Contains, Starts, Finishes, Equals, Greater, Less
}

/*
    Sort on a column of the results
*/
struct CPDataSort {
    1: string column,
    2: CPDataSortDirection direction,
}

/*
    A single search on the results
*/
struct CPDataSearch {
    1: string search, # @utf8
    2: optional string column,
    3: optional bool isFalse,
    4: optional CPDataSearchOperator operator
}

/*
    The basic criteria for any data query.
*/
struct CPDataPaging {
    1: i16 page,
    2: i16 rows,
    3: optional i32 totalRows,
    4: optional i32 filteredRows,
    5: optional list<CPDataSort> sort,
    6: optional list<CPDataSearch> search,
}

/*
    A result set from a single data query.
*/
struct CPDataResult {
    1: CPDataPaging paging,
    4: list<string> columns,
    5: list<list<string>> rows,
}

/*
    A method request
*/
struct CPMethodRequest {
    1: string serviceName,
    2: string methodName,
    3: string paramsJSON, # @utf8
    4: optional string contextJSON, # @utf8
}

/*
    The result of a method call
*/
struct CPMethodResult {
    1: i16 id,
    2: CPMethodRequest request,
    3: bool success,
    4: string resultJSON, # @utf8
}

/*
    List of Containers

    @param  paging
    @param  data        List of ContainerDetails

*/
struct CPlistContainersResult {
    1: CPDataPaging paging,
    2: list<ContainerDetails> data
}

/*
    List of Sites

    @param  paging
    @param  data        List of SiteDetails records

*/
struct CPlistSitesResult {
    1: CPDataPaging paging,
    2: list<SiteDetails> data
}

/*
    List of SiteEnvironments

    @param  paging
    @param  data        List of EnvironmentDetails records

*/
struct CPlistSiteEnvironmentsResult {
    1: CPDataPaging paging,
    2: list<EnvironmentDetails> data
}

/*
    List of Containers in a given Environment

    @param  paging
    @param  data        List of details for Containers in an Environment

*/
struct CPlistEnvironmentContainersResult {
    1: CPDataPaging paging,
    2: list<ContainerEnvironmentDetails> data
}

/*
    List of Domains

    @param  paging
    @param  data        List of Domain details

*/
struct CPlistDomainsResult {
    1: CPDataPaging paging,
    2: list<DomainDetails> data
}

/*
    List of DomainRecords

    @param  paging
    @param  data        List of DomainRecord details

*/
struct CPlistDomainRecordsResult {
    1: CPDataPaging paging,
    2: list<DomainRecordDetails> data
}

/*
    List of Databases
*/
struct CPlistDatabasesResult {
    1: CPDataPaging paging,
    2: list<DatabaseDetails> data
}

/*
    List of Database users
*/
struct CPlistDatabaseUsersResult {
    1: CPDataPaging paging,
    2: list<DatabaseUserDetails> data
}

/*
    List of Database slow logs
*/
struct CPlistDatabaseSlowLogsResult {
    1: CPDataPaging paging,
    2: list<DatabaseSlowLog> data
}

/*
    List of Customer's addresses
*/
struct CPlistAddressesResult {
    1: CPDataPaging paging,
    2: list<CustomerAddressDetails> data
}

/*
    List of Customer's FTP users
*/
struct CPlistFTPUsersResult {
    1: CPDataPaging paging,
    2: list<FTPUser> data
}

/*
    The main splash screen of the Control Panel
    All list results are paginated according to reasonable defaults.  Check the 'paging' value of each for total rows.
*/
struct CPaccountMainResult {
    1: CustomerId             customerId,
    2: CustomerUsername       username,
    3: optional PBA_accountDetails accountDetails,
}

/*
    Control panel methods

    @role control_panel
*/
service CP extends Common {
    /*
        Authenticate a customer against their LDAP entry.
        Return a session id which can then be used for CP calls in lieu of an API key.
    */
    CPSessionId login (
        1: EmailAddress email,
        2: string password,
    ) throws (1: InvalidArguments ouch),

    /*
        Invalidate an authenticated session.
    */
    void logout (),

    /*
        Sign up a new customer.
    */
    CPSessionId signup (
        // Pass through to Customer.create
        1: string           firstName,   # @utf8 @validate length 1-
        2: string           lastName,    # @utf8 @validate length 1-
        3: EmailAddress     email,
        4: string           password,    # @validate length 1-  
        5: CustomerUsername username,
        6: string           companyName, # @utf8 @optional

        // Pass through to Billing.createPaymentMethod
        7: string        cardNumber,     # @secure @validate length 15-16
        8: PBA_paySystem cardPaySystem,
        9: string        cardExpiryDate, # @validate regex /^\d\d\/\d\d$/
        10: string       cardCvvCode,    # @secure @validate regex /^\d{3,4}$/

        // Pass through to Billing.createAccount
        11: PBA_Address     address,
        12: PBA_PhoneNumber phone,
        13: PBA_accountType type,

        // Store in PBAAccount
        14: string promoCode,      # @optional
        15: i32    referralId,     # @optional
        16: string invitationCode, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Find out the logged in customer id
    */
    CustomerId activeCustomerId (),

    /*
        Update password, step one.
        Sends email to user which contains a unique one-time id to be used to reset the password.
    */
    void updatePasswordRequest (
        1: EmailAddress email,
        2: URL baseUrl,         # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Update password, step two.
        Authorized with the given one-time id, change the users password.
    */
    void updatePassword (
        1: CPUpdatePasswordId id,
        2: string password,     # @validate length 1-
    ) throws (1: InvalidArguments ouch),

    /*
        Get pending results and acknowledge them
    */
    list<CPMethodResult> getPendingResults (
        1: list<i16> ids, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        List all the customer's containers.
    */
    CPlistContainersResult listContainers (
        1: CPDataPaging paging,
        2: bool siteHostOnly,  # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        List all the customer's sites.
    */
    CPlistSitesResult listSites (
        1: CPDataPaging paging,
    ) throws (1: InvalidArguments ouch),

    /*
        List a Site's Environments.
    */
    CPlistSiteEnvironmentsResult listSiteEnvironments (
        1: CPDataPaging paging,
        2: SiteId id,
    ) throws (1: InvalidArguments ouch),

    /*
        List an Environment's Containers.
    */
    CPlistEnvironmentContainersResult listEnvironmentContainers (
        1: CPDataPaging paging,
        2: EnvironmentId id,
    ) throws (1: InvalidArguments ouch),
    
    /*
        List a Customer's DNS Domains.
    */
    CPlistDomainsResult listDomains (
        1: CPDataPaging paging,
    ) throws (1: InvalidArguments ouch),

    /*
        List a Customer's Domain Records.
    */
    CPlistDomainRecordsResult listDomainRecords (
        1: CPDataPaging paging,
        2: DomainId id
    ) throws (1: InvalidArguments ouch),

    /*
        List all the customer's Databases.
    */
    CPlistDatabasesResult listDatabases (
        1: CPDataPaging paging,
    ) throws (1: InvalidArguments ouch),

    /*
        List all the customer's Databases.
    */
    CPlistDatabaseUsersResult listDatabaseUsers (
        1: CPDataPaging paging,
        2: DatabaseId id,
    ) throws (1: InvalidArguments ouch),

    /*
        List all the customer's Database slow logs
    */
    CPlistDatabaseSlowLogsResult listDatabaseSlowLogs (
        1: CPDataPaging paging,
        2: DatabaseId id,
    ) throws (1: InvalidArguments ouch),

    /*
        List all the Customer's addresses.
    */
    CPlistAddressesResult listAddresses (
        1: CPDataPaging paging,
    ) throws (1: InvalidArguments ouch),

    /*
        List all the Customer's FTP users.
    */
    CPlistFTPUsersResult listFTPUsers (
        1: CPDataPaging paging,
        2: SiteId siteId,               # @optional
        3: EnvironmentId environmentId, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Account main
    */
    CPaccountMainResult accountMain (
    ) throws (1: InvalidArguments ouch),

    /*
        Get a URL to be used for logging into PBA
    */
    string getPBAUrl (
    ) throws (1: InvalidArguments ouch),

    /*
        Get a list of countries configured for the vendor (passthrough to the Billing provider)
    */
    list<PBA_Country> getCountryList (),

    /*
        Call an async method synchronously
        Provide the service name and method, and the arguments as a JSON hash.
    */
    string callAsyncMethod (
        1: string serviceName,   # @validate length 1-
        2: string methodName,    # @validate length 1-
        3: string argumentsJSON, # @utf8 @validate length 1-
    ) throws (1: InvalidArguments ouch),

    /*
        Fetch all the notices associated with the customer (or global)
    */
    list<CustomerNotice> listNotices (
        1: UnixTime since,       # Ignore notices that were created or updated before this time @optional
    ) throws (1: InvalidArguments ouch),
}
/*
    PBA proxy
    @role internal
*/
service Billing extends Common {
    
    /*
        Create a new account in PBA.
        If you're creating a 'Person', ignore 'admin', 'billing' and 'tech' and set 'name' to the person's full name
        If you're creating a 'Company', ignore 'personal', and set 'name' to the company name
        (AccountAdd)
    */
    PBA_accountId createAccount (
        1: PBA_accountRole role,
        2: PBA_accountType type,
        3: string          name,      # @utf8 @validate length -80
        4: PBA_Address     address,
        5: PBA_Contact     admin,     # @optional
        6: PBA_Contact     billing,   # @optional
        7: PBA_Contact     tech,      # @optional
        8: PBA_Contact     personal,  # @optional
        9: bool            validateOnly, # If true, no account will be created (-1 will be returned upon success) @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Update an account in PBA.
        If you're updating a 'Person', ignore 'admin', 'billing' and 'tech' and set 'name' to the person's full name
        If you're updating a 'Company', ignore 'personal', and set 'name' to the company name
        (AccountUpdate)
    */
    void updateAccount (
        1: PBA_accountId id,
        2: string        name,      # @utf8 @validate length -80
        3: PBA_Address   address,
        4: PBA_Contact   admin,     # @optional
        5: PBA_Contact   billing,   # @optional
        6: PBA_Contact   tech,      # @optional
        7: PBA_Contact   personal,  # @optional
        8: bool          validateOnly, # If true, no update will happen @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Cancels an account and all subscriptions
        (PlaceAccountCancellationOrder)
    */
    void cancelAccount (
        1: PBA_accountId  id,
        2: PBA_reasonCode reason,
        3: string         description, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Look up the account details of a single account
        (AccountDetailsGet)
    */
    PBA_accountDetails getAccountDetails (
        1: PBA_accountId accountId,
    ) throws (1: InvalidArguments ouch),

    /*
        Add a credit card number of file
        (CreditCard2AccountAdd)
    */
    PBA_paymentMethodId createPaymentMethod (
        1: PBA_accountId accountId,
        2: string        cardHolderName, # @utf8 @validate length -40
        3: string        cardNumber,     # @secure @validate length -20
        4: PBA_paySystem paySystem,
        5: string        expiryDate,     # @validate regex /^\d\d\/\d\d$/
        6: string        cvvCode,        # @secure @validate length -4
        7: EmailAddress  email,
        8: PBA_Address   address,
        9: PBA_PhoneNumber phone,
        10: PBA_PhoneNumber fax,         # @optional
        11: bool         useForAutoPayments,
        12: bool         validateOnly, # If true, no payment method will be created (-1 will be returned upon success) @optional
    ) throws (1: InvalidArguments ouch),

    /* 
        Make a payment method (credit card) the default
        (SetDefaultPaymentMethod)
    */
    void setDefaultPaymentMethod (
        1: PBA_accountId accountId,
        2: PBA_paymentMethodId paymentMethodId,
    ) throws (1: InvalidArguments ouch),

    /*
        List an account's credit cards
        (PayToolListForAccountGet)
    */
    list<PBA_PaymentMethod> getPaymentMethodList (
        1: PBA_accountId accountId
    ) throws (1: InvalidArguments ouch),

    /*
        List all the accounts receivable documents of the account
        (ARDoc_Account_GetARDocList)
    */
    list<PBA_arDoc> getAccountsReceivableList (
        1: PBA_accountId accountId
    ) throws (1: InvalidArguments ouch),

    /*
        Create a new account subscription order
        (PlaceOrderAndAuthorize)
    */
    PBA_SubscriptionOrder createSubscriptionOrder (
        1: PBA_accountId       accountId,
        2: PBA_planId          planId,         # @optional
        3: string              planName,       # @optional
        4: PBA_planPeriodId    planPeriodId,   # @optional
        5: string              planPeriodName, # @optional
        6: string              promoCode,      # @optional
        7: PBA_paymentMethodId paymentMethodId, # @optional
        8: IPAddress           customerIP,
        9: string              name,           # @utf8 @optional
        10: string             invitationCode, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Get the status of a subscription order
        (GetOrder)
    */
    PBA_orderStatus getSubscriptionOrderStatus (
        1: PBA_orderId id
    ) throws (1: InvalidArguments ouch),

    /*
        Set the subscription name (for invoicing)
        (XM::updateSubscriptionDescription_API)
    */
    void setSubscriptionName (
        1: PBA_subscriptionId subscriptionId,
        2: string             name,           # @utf8
    ) throws (1: InvalidArguments ouch),

    /*
        Get a list of an account's subscriptions
        (GetHostingSubscriptionList)
    */
    list<PBA_Subscription> getSubscriptionList (
        1: PBA_accountId accountId,
    ) throws (1: InvalidArguments ouch),

    /*
        Update the status of a subscription
        (SubscriptionStatusUpdate)
    */
    void updateSubscriptionStatus (
        1: PBA_subscriptionId id,
        2: PBA_subscriptionStatus status, # @optional
        3: PBA_subscriptionServiceStatus serviceStatus, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Stop a subscription
        (SubscriptionStop)
    */
    void stopSubscription (
        1: PBA_subscriptionId id,
        2: string reason,
    ) throws (1: InvalidArguments ouch),

    /*
        Cancel a subscription
        (PlaceSubscriptionCancellationOrder)
    */
    void cancelSubscription (
        1: PBA_subscriptionId id,
        2: PBA_cancelType type,
        3: PBA_reasonCode reason,
        4: string description,
    ) throws (1: InvalidArguments ouch),

    /*
        Change a subscription to another plan type
        Provide either 'planId' or 'planName' to refer to plan (from getPlanChangeList)
          that is valid for this subscription plan.  ('256M' -> '512M' for example)
        Provide either 'planPeriodId' or 'planPeriodName' to choose a plan period explicitly
          or don't provide a plan period at all and the period will remain the same ('monthly')
    */
    PBA_SubscriptionOrder createSubscriptionChangeOrder (
        1: PBA_subscriptionId subscriptionId,
        2: PBA_planId         planId,         # @optional
        3: string             planName,       # @optional
        4: PBA_planPeriodId   planPeriodId,   # @optional
        5: string             planPeriodName, # @optional
    ) throws (1: InvalidArguments ouch),

    /*
        Get a list of all available Stackable plans
        (PlanListAvailableGet)
    */
    list<PBA_Plan> getPlanList (),

    /*
        List subscription upgrade and downgrades available
    */

    list<PBA_Plan> getPlanChangeList (
        1: PBA_planId planId
    ) throws (1: InvalidArguments ouch),

    /*
        Get a list of a plan's periods
        (PlanPeriodListGet)
    */
    list<PBA_PlanPeriod> getPlanPeriodList (
        1: PBA_planId planId,
    ) throws (1: InvalidArguments ouch),

    /*
        Get a list of an account's available plan resources
        (ResourceListByCategoryGet)
    */
    list<PBA_Resource> getResourceList (),

    /*
        Get a list of resource usage items for a subscription
        (SubscriptionResourcesListGet)
    */
    list<PBA_ResourceUsage> getResourceUsageList (
        1: PBA_subscriptionId subscriptionId,
    ) throws (1: InvalidArguments ouch),

    /*
        Update the resource usage of a subscription
        (ManualResourceUsageUpdate)
    */
    void updateResourceUsage (
        1: PBA_subscriptionId subscriptionId,
        2: PBA_resourceId     resourceId,   # @optional
        3: string             resourceName, # @optional
        4: double             amount,
    ) throws (1: InvalidArguments ouch),

    /*
        Create an invitation for a one-off promo code
    */
    PBA_invitationId createInvitation (
        1: string       nameFirst, # @utf8 @validate length 1-
        2: string       nameLast,  # @utf8 @validate length 1-
        3: EmailAddress email,
        4: string       promoName,
        5: UnixTime     expires,
    ) throws (1: InvalidArguments ouch),

    /*
        Resend an invitation email
    */
    void resendInvitation (
        1: PBA_invitationId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Revoke an invitation by id
    */
    void revokeInvitation (
        1: PBA_invitationId id,
    ) throws (1: InvalidArguments ouch),

    /*
        Get a URL to be used for logging into PBA
    */
    string getPBAUrl (
        1: PBA_accountId accountId,
    ) throws (1: InvalidArguments ouch),

    /*
        Get a list of countries configured for the vendor
    */
    list<PBA_Country> getCountryList (),
}