service.h

Go to the documentation of this file.

/*
 * Copyright 2026 The A11 Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef A11_SERVICE_SERVICE_H_
#define A11_SERVICE_SERVICE_H_
 
#include <memory>
#include <string>
#include <string_view>
#include <vector>
 
#include <absl/status/status.h>
#include <absl/status/statusor.h>
#include <absl/time/time.h>
 
#include "a11/actions/registry.h"
#include "a11/concurrency/future.h"
#include "a11/data/types.h"
#include "a11/net/describe_endpoint.h"
#include "a11/net/wire_stream.h"
#include "a11/service/session.h"
 
namespace a11::service {
 
using OnServiceConnection = std::function<a11::Task(
    std::shared_ptr<Session>, std::shared_ptr<net::WireStream>)>;
 
struct ServiceOptions {
  SessionOptions session_options;
  bool copy_registry_per_connection = false;
  data::ByteMap session_headers;
  absl::Duration drain_timeout = absl::Seconds(30);
  OnSessionStreamMessage on_stream_message;
  OnSessionStreamDone on_stream_done;
 
  absl::Status Validate() const;
};
 
class Service : public std::enable_shared_from_this<Service> {
 public:
  static absl::StatusOr<std::shared_ptr<Service>> Create(
      std::shared_ptr<actions::ActionRegistry> action_registry = nullptr,
      OnServiceConnection on_connection = {}, ServiceOptions options = {});
 
  ~Service();
 
  Service(const Service&) = delete;
  Service& operator=(const Service&) = delete;
 
  // --- what the service can do ------------------------------------------
 
  [[nodiscard]] std::shared_ptr<actions::ActionRegistry> GetActionRegistry()
      const;
  absl::Status SetActionRegistry(
      const std::shared_ptr<actions::ActionRegistry>& action_registry);
  absl::Status SetOnConnection(OnServiceConnection on_connection);
 
  absl::StatusOr<std::string> Describe(std::string_view name,
                                       std::string_view query) const;
 
  [[nodiscard]] net::DescribeActionsHandler DescribeHandler();
 
  // --- the sole join point with a transport ------------------------------
 
  a11::Task Serve(std::shared_ptr<net::WireStream> stream,
                  StreamMode mode = StreamMode::kAccept);
  absl::StatusOr<std::shared_ptr<Session>> StartStreamHandler(
      const std::shared_ptr<net::WireStream>& stream,
      StreamMode mode = StreamMode::kAccept);
  absl::Status AddStreamToSession(
      std::string_view session_id,
      const std::shared_ptr<net::WireStream>& stream,
      StreamMode mode = StreamMode::kAccept);
 
  // --- who is connected -------------------------------------------------
 
  [[nodiscard]] std::vector<std::string> SessionIds() const;
  absl::StatusOr<std::shared_ptr<Session>> GetSession(
      std::string_view session_id) const;
  absl::StatusOr<std::shared_ptr<Session>> GetSessionForStream(
      std::string_view stream_id) const;
  [[nodiscard]] size_t SessionCount() const;
 
  // --- lifecycle --------------------------------------------------------
 
  [[nodiscard]] bool accepting() const;
  absl::Status StopAccepting();
  a11::Task Drain(absl::Duration timeout = absl::InfiniteDuration());
  absl::Status Abort(const absl::Status& status);
  [[nodiscard]] a11::Task Done() const;
 
 private:
  // Public only so this translation unit's helpers can name it; the definition
  // lives in the .cc and is not part of the API.
 public:
  struct State;
 
 private:
  explicit Service(std::shared_ptr<State> state) : state_(std::move(state)) {}
 
  // A shared_ptr rather than inline pImpl storage: every in-flight connection
  // task captures the state and unregisters itself from it when its session
  // finishes, so the state has to be able to outlive this handle.
  std::shared_ptr<State> state_;
};
 
}  // namespace a11::service
 
#endif  // A11_SERVICE_SERVICE_H_