Feat/user discovery

README.md

@@ -206,6 +206,25 @@ LineTalk is designed for fluid, 100% keyboard-driven interaction:
 | <kbd>?</kbd> / <kbd>Ctrl+H</kbd> / <kbd>F1</kbd> | Global | Open **Interactive Keybinding Help** |
 | <kbd>q</kbd> / <kbd>Ctrl+C</kbd> | Global | Quit LineTalk cleanly |
 
+### Find Someone And Chat
+
+Press `Esc` if you are typing, then `n` to open New Direct Message. Enter at least
+two characters of a username. Search is case-insensitive and matches username
+prefixes, returning up to 20 users with their display names and handles.
+Use the up/down arrows to select a result, `Enter` to open the conversation, or
+`Esc` to cancel. Existing conversations are reused; new conversations are saved
+on the server before appearing in the sidebar. Press `i` to start typing.
+
+Discovery is available to authenticated users through
+`GET /api/v1/users/search?q=...`. Results contain only ID, name, and username and
+exclude your own account. Friendship requests and private discovery settings are
+not part of this feature.
+
+Database integration tests require `TEST_DATABASE_URL` pointing to a disposable
+PostgreSQL database. They apply the project migrations and test search and
+concurrent DM creation. The password-free query test also requires permission to
+create a temporary test role. Run them with `make test-api`.
+
 ---
 
 ## 📋 Makefile Reference

internal/api/db/migrations/20261005212029_add_idx_users_lower_username_pattern.sql

@@ -0,0 +1,10 @@
+-- +goose Up
+-- +goose StatementBegin
+CREATE INDEX IF NOT EXISTS idx_users_lower_username_pattern 
+ON users (LOWER(username) text_pattern_ops);
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+DROP INDEX IF EXISTS idx_users_lower_username_pattern;
+-- +goose StatementEnd

internal/api/db/query/conversation.sql

@@ -16,20 +16,14 @@ new_conv AS (
     FROM
         params
     ON CONFLICT (user_min_id, user_max_id) WHERE is_deleting = FALSE AND user_min_id IS NOT NULL
-    DO NOTHING
+    -- RETURNING also exposes a concurrent winner outside this statement's snapshot.
+    DO UPDATE SET user_min_id = EXCLUDED.user_min_id
     RETURNING
         id
 ),
 
 target_conv AS (
     SELECT id FROM new_conv
-    UNION ALL
-    SELECT c.id
-    FROM conversations c, params p
-    WHERE c.user_min_id = p.min_id
-      AND c.user_max_id = p.max_id
-      AND c.is_deleting = FALSE
-    LIMIT 1
 ),
 
 inserted_participants AS (
@@ -51,8 +45,10 @@ SELECT
     u.username
 FROM
     target_conv tc
-JOIN participants p ON p.conv_id = tc.id
-JOIN users u ON u.id = p.user_id;
+-- Base-table scans cannot see participants inserted by a sibling CTE.
+CROSS JOIN (VALUES (sqlc.arg(user_id)::bigint), (sqlc.arg(user_id_2)::bigint)) AS requested(id)
+JOIN users u ON u.id = requested.id
+ORDER BY u.id;
 
 -- name: GetConversationsByUserId :many
 WITH

internal/api/db/query/users.sql

@@ -10,6 +10,15 @@ RETURNING
     created_at,
     updated_at;
 
+-- name: SearchUsers :many
+SELECT id, name, username
+FROM users
+WHERE id <> sqlc.arg(user_id)::bigint
+  AND LOWER(username) LIKE LOWER(sqlc.arg(pattern)::text) ESCAPE '\'
+ORDER BY (LOWER(username) = LOWER(sqlc.arg(query)::text)) DESC,
+         LOWER(username) COLLATE "C", username COLLATE "C", id
+LIMIT 20;
+
 -- name: GetUserByUsername :one
 SELECT
     id,

internal/api/middleware/ratelimit.go

@@ -60,7 +60,7 @@ func AuthRateLimiter(ctx context.Context, ratePerMinute float64, burst int) gin.
 			c.Header("Retry-After", "15")
 			c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{
 				"success": false,
-				"error":   "Too many unauthenticated attempts. Please slow down and try again.",
+				"error":   "Too many requests. Please slow down and try again.",
 			})
 
 			return

internal/api/router/router.go

@@ -48,6 +48,7 @@ func NewRouter(h Handlers, ctx context.Context) *gin.Engine {
 	subRouter.Use(middleware.Auth())
 	{
 		// users routes
+		subRouter.GET("/users/search", middleware.AuthRateLimiter(ctx, 60, 20), h.User.SearchUsers)
 		subRouter.GET(
 			"/users/:id",
 			middleware.ValidateURIParams[types.URLParamInt](),

internal/api/users/dto.go

@@ -1,6 +1,16 @@
 // Package users
 package users
 
+type PublicUser struct {
+	ID       int64  `json:"id"`
+	Name     string `json:"name"`
+	Username string `json:"username"`
+}
+
+type SearchUsersResponse struct {
+	Users []PublicUser `json:"users"`
+}
+
 type CreateUserType struct {
 	Name     string
 	Username string

internal/api/users/handler.go

@@ -10,6 +10,7 @@ import (
 )
 
 type UserHandlerInt interface {
+	SearchUsers(c *gin.Context)
 	GetUserByUsername(c *gin.Context)
 	GetUserByID(c *gin.Context)
 }
@@ -24,6 +25,21 @@ func NewUserHandler(s UserServiceInt) *UserHandler {
 
 var _ UserHandlerInt = (*UserHandler)(nil)
 
+func (h *UserHandler) SearchUsers(c *gin.Context) {
+	userID, ok := c.Get("userId")
+	id, valid := userID.(int64)
+	if !ok || !valid || id <= 0 {
+		helpers.WriteError(c, apierrs.NewUnauthorizedError("unauthorized"))
+		return
+	}
+	result, err := h.s.SearchUsers(c.Request.Context(), id, c.Query("q"))
+	if err != nil {
+		helpers.WriteError(c, err)
+		return
+	}
+	helpers.WriteJSON(c, http.StatusOK, result)
+}
+
 func (h *UserHandler) GetUserByUsername(c *gin.Context) {
 
 	ctx := c.Request.Context()

internal/api/users/repository.go

@@ -4,19 +4,22 @@ import (
 	"context"
 	"fmt"
 	"log"
+	"strings"
 	"time"
 
 	"github.com/DanielJohn17/tui-chat/internal/api/database"
 )
 
 type UserRepositoryInt interface {
+	SearchUsers(ctx context.Context, userID int64, query string) ([]PublicUser, error)
 	CreateUser(ctx context.Context, user CreateUserType) (*CreateUserResponseType, error)
 	GetUserByUsername(ctx context.Context, username string) (*GetUserResponseType, error)
 	GetUserByID(ctx context.Context, id int64) (*GetUserResponseType, error)
 	DeleteUser(ctx context.Context, id int64) (*DeleteUserResponseType, error)
 }
 
 type UserQuerier interface {
+	SearchUsers(ctx context.Context, arg database.SearchUsersParams) ([]database.SearchUsersRow, error)
 	CreateUser(ctx context.Context, arg database.CreateUserParams) (database.CreateUserRow, error)
 	GetUserByUsername(ctx context.Context, username string) (database.GetUserByUsernameRow, error)
 	GetUserById(ctx context.Context, id int64) (database.GetUserByIdRow, error)
@@ -33,6 +36,23 @@ func NewUserRepository(q UserQuerier) *UserRepository {
 
 var _ UserRepositoryInt = (*UserRepository)(nil)
 
+func (r *UserRepository) SearchUsers(ctx context.Context, userID int64, query string) ([]PublicUser, error) {
+	pattern := strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(query) + "%"
+	rows, err := r.q.SearchUsers(ctx, database.SearchUsersParams{
+		UserID:  userID,
+		Pattern: pattern,
+		Query:   query,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("search users: %w", err)
+	}
+	result := make([]PublicUser, 0, len(rows))
+	for _, row := range rows {
+		result = append(result, PublicUser{ID: row.ID, Name: row.Name, Username: row.Username})
+	}
+	return result, nil
+}
+
 func (r *UserRepository) CreateUser(
 	ctx context.Context,
 	user CreateUserType,

internal/api/users/service.go

@@ -2,11 +2,14 @@ package users
 
 import (
 	"context"
+	"strings"
+	"unicode/utf8"
 
 	"github.com/DanielJohn17/tui-chat/internal/api/apierrs"
 )
 
 type UserServiceInt interface {
+	SearchUsers(ctx context.Context, userID int64, query string) (*SearchUsersResponse, error)
 	CreateUser(
 		ctx context.Context,
 		input CreateUserType,
@@ -38,6 +41,21 @@ func NewUserService(r UserRepositoryInt) *UserService {
 
 var _ UserServiceInt = (*UserService)(nil)
 
+func (s *UserService) SearchUsers(ctx context.Context, userID int64, query string) (*SearchUsersResponse, error) {
+	query = strings.TrimSpace(query)
+	if n := utf8.RuneCountInString(query); !utf8.ValidString(query) || n < 2 || n > 20 {
+		return nil, apierrs.NewBadRequestError("query must be between 2 and 20 characters")
+	}
+	result, err := s.r.SearchUsers(ctx, userID, query)
+	if err != nil {
+		return nil, apierrs.NewInternalServerError("error searching users", err)
+	}
+	if result == nil {
+		result = []PublicUser{}
+	}
+	return &SearchUsersResponse{Users: result}, nil
+}
+
 func (s *UserService) CreateUser(
 	ctx context.Context,
 	input CreateUserType,

internal/tui/app.go

@@ -1,6 +1,7 @@
 package tui
 
 import (
+	"context"
 	"fmt"
 	"time"
 
@@ -113,11 +114,13 @@ type AppModel struct {
 	notificationText string
 	notificationID   int64
 
-	authView    auth.Model
-	sidebarView *sidebar.Model
-	chatView    chat.Model
-	profileView profile.Model
-	newDMView   modals.NewDMModel
+	authView            auth.Model
+	sidebarView         *sidebar.Model
+	chatView            chat.Model
+	profileView         profile.Model
+	newDMView           modals.NewDMModel
+	discoveryGeneration uint64
+	discoveryCancel     context.CancelFunc
 }
 
 func NewApp(c client.Client) AppModel {
@@ -291,10 +294,18 @@ func (m AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		return m, nil
 
 	case profile.LogoutMsg:
+		m.cancelDiscovery()
+		m.modal = ModalNone
 		_ = m.client.Logout()
 		m.state = StateAuth
 		m.authView.SetErrorMessage("Logged out successfully.")
 		return m, nil
+	case DiscoveryDebounceMsg:
+		return m.handleDiscoveryDebounce(msg)
+	case DiscoverySearchMsg:
+		return m.handleDiscoverySearch(msg)
+	case DiscoveryOpenMsg:
+		return m.handleDiscoveryOpen(msg)
 	}
 
 	// 1. Modals capture input when open

internal/tui/client/client.go

@@ -1,5 +1,13 @@
 package client
 
+import "context"
+
+type UserSummary struct {
+	ID       int64  `json:"id"`
+	Name     string `json:"name"`
+	Username string `json:"username"`
+}
+
 type Profile struct {
 	ID        int64  `json:"id"`
 	Name      string `json:"name"`
@@ -88,6 +96,8 @@ type Client interface {
 	SetSessionPath(string)
 
 	// REST Data operations
+	SearchUsers(context.Context, string) ([]UserSummary, error)
+	OpenDirectConversation(context.Context, int64) (Chat, error)
 	FetchChats() ([]Chat, error)
 	Chats() []Chat
 	SetChats([]Chat)