// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// API exposed by the ChromeOS mojo service manager.

// NOTE: This mojom should be kept in sync with the copy in ChromeOS's repo in
// src/platform2/mojo_service_manager/lib/mojom/service_manager.mojom

// Namespace of this mojom should be migrated to namespace ash once we confirms
// Lacros won't use mojo service manager in the future.

module chromeos.mojo_service_manager.mojom;

import "mojo/public/mojom/base/time.mojom";

// Shares and manages mojo services between all the processes running on
// ChromeOS. This is provided by the ChromeOS mojo service manager daemon.
// The argument |service_name| should match the regex ([a-zA-Z0-9._\-]+). It is
// used for identifying the services and for the ACLs.
//
// Next MinVersion: 1
// Next Method ID: 4
interface ServiceManager {
  // Registers a service to the service manager. Callers should set disconnect
  // handler on the corresponding mojo receiver of |service_provider| to handle
  // errors.
  Register@0(string service_name,
             pending_remote<ServiceProvider> service_provider);

  // Requests a service from the service manager. The |receiver| will be bound
  // to the service. In the case that the service is not registered, if
  // |timeout| is null, the |receiver| will be bound after the service is
  // available. If |timeout| is not null and the |receiver| cannot be bound
  // after |timeout|, it will be reset. Callers should set disconnect handler on
  // the corresponding mojo remote of |receiver| to handle errors.
  Request@1(string service_name, mojo_base.mojom.TimeDelta? timeout,
            handle<message_pipe> receiver);

  // Queries the state of a service.
  Query@2(string service_name) => (ErrorOrServiceState result);

  // Registers an observer to observe the state of services. The observer can
  // only receive the events related to the services which the callers are
  // allowed to request. Callers should set disconnect handler on the
  // corresponding mojo receiver of |observer| to handle errors.
  AddServiceObserver@3(pending_remote<ServiceObserver> observer);
};

// Provides a service to other processes. Each provider process implements this
// for each mojo service and registers each of them to the service manager. This
// will only be called by the service manager and will not be exported to other
// processes directly.
//
// Next MinVersion: 1
// Next Method ID: 1
interface ServiceProvider {
  // Requests to bind the |receiver| to the corresponding mojo interface.
  // The service manager checks the policies and calling this if the requester
  // is allowed. The |client_identity| is set by the service manager for
  // identifying the requester process. This can be used for more detail ACLs if
  // needed.
  // Note: the implementations can reset |receiver| to return errors. They
  // should use the error codes defined in |ErrorCode| enum when returning
  // errors.
  Request@0(ProcessIdentity client_identity,
            handle<message_pipe> receiver);
};

// Observes the service events. Requester processes implement this and register
// it to the service manager.
//
// Next MinVersion: 1
// Next Method ID: 1
interface ServiceObserver {
  // Is called when service events occur.
  OnServiceEvent@0(ServiceEvent event);
};

// The identity information about a process.
//
// Next MinVersion: 1
// Next Field ID: 4
struct ProcessIdentity {
  // The SELinux security context.
  string security_context@0;
  // The process id.
  uint32 pid@1;
  // The user / group id.
  uint32 uid@2;
  uint32 gid@3;
};

// The result of ServiceManager::Query.
//
// Next MinVersion: 1
// Next Field ID: 3
[Extensible]
union ErrorOrServiceState {
  // The default value for forward compatibility. All the unknown type will be
  // mapped to this.
  [Default] uint8 default_type@0;
  // The result if succeeds.
  ServiceState state@1;
  // The error if fails.
  Error error@2;
};

// The state of a service.
//
// Next MinVersion: 1
// Next Field ID: 3
[Extensible]
union ServiceState {
  // The default value for forward compatibility. All the unknown type will be
  // mapped to this.
  [Default] uint8 default_type@0;
  // The state of a registered service.
  RegisteredServiceState registered_state;
  // The state of a unregistered service.
  UnregisteredServiceState unregistered_state;
};

// The state of a registered service.
//
// Next MinVersion: 1
// Next Field ID: 1
struct RegisteredServiceState {
  // The identity of the owner of the service.
  ProcessIdentity owner@0;
};

// The state of a unregistered service.
//
// Next MinVersion: 1
// Next Field ID: 0
struct UnregisteredServiceState {
};

// The event about a service.
//
// Next MinVersion: 1
// Next Field ID: 3
struct ServiceEvent {
  [Extensible]
  enum Type {
    // The default value for forward compatibility. All the unknown value will
    // be mapped to this.
    [Default] kUnknown,
    // The service is registered.
    kRegistered,
    // The service is not registered.
    kUnRegistered,
  };

  Type type@0;
  // The name of the service which triggers the event.
  string service_name@1;
  // The dispatcher of the event. It is the process which registered or
  // unregistered the service.
  ProcessIdentity dispatcher@2;
};

// A generic error type for functions to return error.
//
// Next MinVersion: 1
// Next Field ID: 2
struct Error {
  ErrorCode code@0;
  string message@1;
};

// The error code for |struct Error| and the disconnect handlers. This is used
// in the disconnect reason of all the mojo handles (namely, message pipe,
// receiver and remote) which are sent to |ServiceManager|.
// Note that in the disconnect handlers, this is casted to |uint32| and has no
// guarantee that the value can be casted back to this. Use
// |mojo::ConvertIntToMojoEnum()| for casting.
//
// NextMinVersion: 1
[Extensible]
enum ErrorCode {
  // The default value for forward compatibility. In struct |Error|, all the
  // unknown value will be mapped to this.
  // In disconnect handlers, if the handle is reset without a reason, the error
  // code is 0. So this enum starts from 1 to be distinguish from that.
  [Default] kUnknown = 1,
  // Timeout is reached.
  kTimeout,
  // The caller is not permit to perform the operation.
  kPermissionDenied,
  // The service has already been registered.
  kServiceAlreadyRegistered,
  // The service cannot be found.
  kServiceNotFound,
  // Unexpected os error.
  kUnexpectedOsError,
};