chattolib/proto/chatto/api/v1/message_search.proto

syntax = "proto3";

package chatto.api.v1;

import "buf/validate/validate.proto";
import "chatto/api/v1/message_types.proto";
import "chatto/api/v1/room_timeline.proto";
import "chatto/api/v1/rooms.proto";
import "chatto/api/v1/threads.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

// Ordering for message or grouped-thread search results.
enum MessageSearchOrder {
  // Use relevance order.
  MESSAGE_SEARCH_ORDER_UNSPECIFIED = 0;
  // Highest message score first; grouped results use their best matching message.
  MESSAGE_SEARCH_ORDER_RELEVANCE = 1;
  // Newest matching message first, also when results are grouped.
  MESSAGE_SEARCH_ORDER_NEWEST = 2;
  // Return threads with the most recent activity first. Requires thread grouping.
  MESSAGE_SEARCH_ORDER_THREAD_ACTIVITY = 3;
  // Newest root-message creation first, with unknown dates last. Requires thread
  // grouping. Older servers can reject this order.
  MESSAGE_SEARCH_ORDER_THREAD_CREATED = 4;
}

// Candidate scope, intersected with the caller's current access and query filters.
enum MessageSearchScope {
  // Search all accessible messages. This is the existing default.
  MESSAGE_SEARCH_SCOPE_UNSPECIFIED = 0;
  // Search roots and replies in followed threads, including direct messages.
  MESSAGE_SEARCH_SCOPE_FOLLOWED_THREADS = 1;
}

// Determines the result type and pagination unit.
enum MessageSearchGroupBy {
  // Return individual matching messages.
  MESSAGE_SEARCH_GROUP_BY_UNSPECIFIED = 0;
  // Return distinct thread rows. A root without replies is also a thread.
  MESSAGE_SEARCH_GROUP_BY_THREAD = 1;
}

// Current availability of message search on this server.
enum MessageSearchState {
  // The server did not report a meaningful state.
  MESSAGE_SEARCH_STATE_UNSPECIFIED = 0;
  // Search is disabled by the server operator.
  MESSAGE_SEARCH_STATE_DISABLED = 1;
  // Search is enabled but its provider has not established index state yet.
  MESSAGE_SEARCH_STATE_STARTING = 2;
  // The provider is rebuilding or catching up and cannot answer queries yet.
  MESSAGE_SEARCH_STATE_INDEXING = 3;
  // Search is ready to answer queries.
  MESSAGE_SEARCH_STATE_READY = 4;
  // Search can answer queries but has a known non-fatal limitation.
  MESSAGE_SEARCH_STATE_DEGRADED = 5;
  // Search is enabled but no provider can currently answer.
  MESSAGE_SEARCH_STATE_UNAVAILABLE = 6;
}

// Request to search current message bodies visible to the authenticated user.
message SearchMessagesRequest {
  // Required query expression. Words are required terms, quoted text is an
  // exact phrase, and `AND` may separate terms. The query also accepts `in:`,
  // `from:`, `before:`, `after:`, and `has:attachment` filters; a recognized
  // filter may be used without a word or phrase.
  string query = 1 [(buf.validate.field).string = {
    min_len: 1
    max_bytes: 1024
  }];
  // Optional room-ID scope. The server intersects this room with rooms the
  // current user may read and with any `in:` filters in query.
  optional string room_id = 2 [(buf.validate.field).string = {
    min_len: 1
    max_bytes: 128
  }];
  // Optional author-ID scope. The server intersects this author with any
  // `from:` filters in query.
  optional string author_id = 3 [(buf.validate.field).string = {
    min_len: 1
    max_bytes: 128
  }];
  // Exclusive lower bound on message creation time. The stricter bound wins
  // when query also contains `after:`.
  google.protobuf.Timestamp created_after = 4;
  // Exclusive upper bound on message creation time. The stricter bound wins
  // when query also contains `before:`.
  google.protobuf.Timestamp created_before = 5;
  // When true, return only messages that currently have attachments.
  bool has_attachments = 6;
  // Defaults to relevance in both result modes. Thread activity order requires
  // thread grouping; newest order uses matching-message creation time.
  MessageSearchOrder order = 7 [(buf.validate.field).enum.defined_only = true];
  // Maximum results to return (messages or distinct threads). Zero uses 50; the
  // maximum is 100. Stale or no-longer-visible provider hits are omitted, so a
  // page may contain fewer messages than requested even when next_cursor is
  // present.
  uint32 page_size = 8 [(buf.validate.field).uint32.lte = 100];
  // Opaque cursor returned by the preceding response. It is bound to the
  // authenticated user and every other query field.
  string cursor = 9 [(buf.validate.field).string.max_bytes = 8192];
  // Candidate scope. Followed threads are selected before result pagination.
  MessageSearchScope scope = 10 [(buf.validate.field).enum.defined_only = true];
  // Result grouping. The server deduplicates threads before pagination.
  MessageSearchGroupBy group_by = 11 [(buf.validate.field).enum.defined_only = true];
  // Select root authors within FOLLOWED_THREADS before search and pagination.
  // Other scopes require UNSPECIFIED. This does not restrict reply authors;
  // author_id and from: still select the authors of matching messages.
  ThreadRootAuthorFilter root_author_filter = 12 [(buf.validate.field).enum.defined_only = true];
}

// One current, authorized match. With thread grouping, each result represents
// one thread and message is its best match in the selected order.
message MessageSearchResult {
  // Current renderable message that matched the query.
  Message message = 1;
  // Search-provider relevance score. Higher values are more relevant for the
  // same query. Clients may merge results from servers using compatible
  // search implementations by this value.
  double relevance_score = 2;
  // Present only with THREAD grouping. The matching message can be a reply;
  // the root and latest reply in this context need not match the query.
  ThreadSearchContext thread_context = 3;
}

// One ordered page of current, authorized message or thread results. Pagination reads a live
// search index rather than a pinned snapshot, so results may move, repeat, or
// disappear between page requests while the index advances.
message SearchMessagesResponse {
  // Ordered matches. With THREAD grouping, one result per matching thread.
  // Otherwise each result is one message, without thread_context.
  repeated MessageSearchResult results = 1;
  // Opaque cursor for the next page in the selected result mode.
  // Empty means no more matches. Live activity can reorder thread pages.
  string next_cursor = 2;
  // Total distinct matching threads. Present only when group_by is THREAD.
  optional uint64 thread_total_count = 4;
  // Related entities for grouped results, avoiding per-row reads.
  RoomTimelineIncludes includes = 5;
}

// Current context for a grouped match. The viewer need not follow this thread.
// Search evidence stays on the containing MessageSearchResult.
message ThreadSearchContext {
  // Renderable root message, when still visible.
  Message root_message = 1;
  // Room containing this thread.
  RoomSummary room = 2;
  // Current thread metadata and viewer follow/read state.
  ThreadSummary thread = 3;
  // Most recent visible reply, when present; it need not match the query.
  Message latest_reply = 4;
  // Conversation-label participants for direct messages; empty for channels.
  repeated string direct_message_participant_user_ids = 5;
}

// Request for current message-search availability.
message GetStatusRequest {}

// Current message-search availability.
message GetStatusResponse {
  reserved 2, 3;
  reserved "indexed_event_count", "target_event_count";

  // Current feature/provider state.
  MessageSearchState state = 1;
  // Suggested delay before checking again while search is not ready.
  google.protobuf.Duration retry_after = 4;
}

// Searches current message content visible to an authenticated user.
service MessageSearchService {
  // Reports whether the operator enabled Search and whether its provider can
  // currently answer. This method remains available when Search is disabled.
  rpc GetStatus(GetStatusRequest) returns (GetStatusResponse);
  // Searches current message bodies in rooms where the caller is a member.
  // Scope and grouping are independent, including for direct messages. THREAD
  // grouping returns one row per matching root and its replies. Scope, grouping,
  // and ordering are part of the cursor scope. Unsupported combinations return
  // INVALID_ARGUMENT. Existing requests return individual messages by default.
  // Results also require message.read or a matching thread relationship with
  // message.read-interactions. Results are authorized and hydrated from current Chatto state
  // after provider matching. Returns FAILED_PRECONDITION when Search is
  // disabled and UNAVAILABLE when its provider is not ready.
  rpc SearchMessages(SearchMessagesRequest) returns (SearchMessagesResponse);
}