HTTP API: a chat's recent messages, and sending a message (closes #5)

GET /api/v1/chats/{id}/messages returns the messages among a chat's
last count items (default 20, at most 100), oldest first. POST sends a
text, waits for the chat client's answer and returns 201 with the
message as sent. A chat the bot does not have is 404, a contact who
deleted the chat is 409, a text too long for one message is 413, and
any other failure is 500 with a chosen sentence.

The chat client spells out a message's formatting in its answer, up to
26 times the text's length, so 100 items in one answer can pass the
16 MiB read limit and end the connection. Items are read five at a
time.

Model: opus-5-5

internal/api/api.go

@@ -1,5 +1,5 @@
 // Package api is the bot's HTTP API, through which another program
-// reads the bot's chats.
+// reads the bot's chats and sends messages in them.
 //
 // Every request must carry the credential, as "Authorization: Bearer
 // {credential}"; with no credential configured, every request is
@@ -47,6 +47,17 @@ const (
 type ChatClient interface {
 	// Contacts returns the contacts of the user userID.
 	Contacts(ctx context.Context, userID int64) ([]simplex.Contact, error)
+
+	// ChatItems returns the last count items of the chat with a
+	// contact, oldest first.
+	ChatItems(
+		ctx context.Context, contactID int64, count int,
+	) ([]simplex.ChatItem, error)
+
+	// SendMessage sends a text message to a contact and returns it.
+	SendMessage(
+		ctx context.Context, contactID int64, text string,
+	) (simplex.ChatItem, error)
 }
 
 // Params configures New.
@@ -86,6 +97,8 @@ func New(p Params) *http.Server {
 	})
 	router.Route("/api/v1", func(r chi.Router) {
 		r.Get("/chats", h.handleChats())
+		r.Get("/chats/{id}/messages", h.handleMessages())
+		r.Post("/chats/{id}/messages", h.handleSend())
 	})
 
 	return &http.Server{

internal/api/api_test.go

@@ -22,19 +22,24 @@ const (
 	bearer     = "Bearer " + credential
 
 	chatsPath    = "/api/v1/chats"
+	messagesPath = "/api/v1/chats/3/messages"
 	unauthorized = `{"error":"unauthorized"}` + "\n"
 )
 
 var errChat = errors.New("sqlite: database is locked at /var/lib/simplexcalc")
 
 // fakeClient stands in for the chat client. It answers with contacts,
-// or with err, and remembers what it was asked.
+// items or sent, or with err, and remembers what it was asked.
 type fakeClient struct {
 	contacts []simplex.Contact
+	items    []simplex.ChatItem
+	sent     simplex.ChatItem
 	err      error
 
-	userID      int64
-	hadDeadline bool
+	userID, contactID int64
+	count             int
+	text              string
+	hadDeadline       bool
 }
 
 func (f *fakeClient) Contacts(
@@ -46,6 +51,24 @@ func (f *fakeClient) Contacts(
 	return f.contacts, f.err
 }
 
+func (f *fakeClient) ChatItems(
+	ctx context.Context, contactID int64, count int,
+) ([]simplex.ChatItem, error) {
+	f.contactID, f.count = contactID, count
+	_, f.hadDeadline = ctx.Deadline()
+
+	return f.items, f.err
+}
+
+func (f *fakeClient) SendMessage(
+	ctx context.Context, contactID int64, text string,
+) (simplex.ChatItem, error) {
+	f.contactID, f.text = contactID, text
+	_, f.hadDeadline = ctx.Deadline()
+
+	return f.sent, f.err
+}
+
 func newAPI(token string, client api.ChatClient) *http.Server {
 	return api.New(api.Params{
 		Log:    slog.New(slog.DiscardHandler),
@@ -168,6 +191,10 @@ func TestNoPathIsExempt(t *testing.T) {
 			http.MethodPost, chatsPath, bearer,
 			http.StatusMethodNotAllowed, `{"error":"method not allowed"}` + "\n",
 		},
+		{
+			http.MethodPost, messagesPath, "",
+			http.StatusUnauthorized, unauthorized,
+		},
 	} {
 		rec := request(t, srv, tc.method, tc.path, tc.auth)
 		if rec.Code != tc.want || rec.Body.String() != tc.body {

internal/api/messages.go

@@ -0,0 +1,217 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"sneak.berlin/go/simplexcalc/internal/simplex"
+)
+
+const (
+	// defaultCount and maxCount bound how many of a chat's last items a
+	// request for its messages reads.
+	defaultCount = 20
+	maxCount     = 100
+
+	// noSuchChat answers a request naming a chat the bot does not have.
+	noSuchChat = "no such chat"
+)
+
+// message is how the API shows a message, wherever it shows one.
+type message struct {
+	ID        int64     `json:"id"`
+	Direction string    `json:"direction"`
+	Type      string    `json:"type"`
+	Text      string    `json:"text"`
+	Time      time.Time `json:"time"`
+}
+
+// newMessage returns the message a chat item holds, and false for an
+// item that holds none: the chat client also records events in a chat,
+// such as the contact connecting.
+func newMessage(item simplex.ChatItem) (message, bool) {
+	var direction string
+
+	switch item.Content.Type {
+	case "rcvMsgContent":
+		direction = "received"
+	case "sndMsgContent":
+		direction = "sent"
+	default:
+		return message{}, false
+	}
+
+	content := item.Content.MsgContent
+	if content == nil {
+		return message{}, false
+	}
+
+	return message{
+		ID:        item.Meta.ItemID,
+		Direction: direction,
+		Type:      content.Type,
+		Text:      content.Text,
+		Time:      item.Meta.ItemTs,
+	}, true
+}
+
+// handleMessages answers with the messages among a chat's last count
+// items, oldest first.
+func (h *handlers) handleMessages() http.HandlerFunc {
+	type response struct {
+		Messages []message `json:"messages"`
+	}
+
+	return func(w http.ResponseWriter, r *http.Request) {
+		contactID, ok := chatID(r)
+		if !ok {
+			h.respondError(w, http.StatusNotFound, noSuchChat)
+
+			return
+		}
+
+		count, ok := messageCount(r)
+		if !ok {
+			h.respondError(w, http.StatusBadRequest,
+				"count must be a whole number from 1 to "+strconv.Itoa(maxCount))
+
+			return
+		}
+
+		items, err := h.client.ChatItems(r.Context(), contactID, count)
+		if err != nil {
+			h.respondChatError(w, err, "reading a chat's messages",
+				"the messages could not be read")
+
+			return
+		}
+
+		messages := make([]message, 0, len(items))
+
+		for _, item := range items {
+			if m, ok := newMessage(item); ok {
+				messages = append(messages, m)
+			}
+		}
+
+		h.respond(w, http.StatusOK, response{Messages: messages})
+	}
+}
+
+// handleSend sends the text in the request's body to a chat, and answers
+// with the message sent.
+func (h *handlers) handleSend() http.HandlerFunc {
+	type request struct {
+		Text string `json:"text"`
+	}
+
+	type response struct {
+		Message message `json:"message"`
+	}
+
+	return func(w http.ResponseWriter, r *http.Request) {
+		contactID, ok := chatID(r)
+		if !ok {
+			h.respondError(w, http.StatusNotFound, noSuchChat)
+
+			return
+		}
+
+		body, err := io.ReadAll(r.Body)
+
+		var tooLarge *http.MaxBytesError
+		if errors.As(err, &tooLarge) {
+			h.respondError(w, http.StatusRequestEntityTooLarge, "the body is too large")
+
+			return
+		}
+
+		var req request
+
+		if err != nil || json.Unmarshal(body, &req) != nil {
+			h.respondError(w, http.StatusBadRequest,
+				`the body must be JSON such as {"text":"hello"}`)
+
+			return
+		}
+
+		if req.Text == "" {
+			h.respondError(w, http.StatusBadRequest, "text is empty")
+
+			return
+		}
+
+		item, err := h.client.SendMessage(r.Context(), contactID, req.Text)
+		if err != nil {
+			h.respondChatError(w, err, "sending a message",
+				"the message could not be sent")
+
+			return
+		}
+
+		sent, ok := newMessage(item)
+		if !ok {
+			h.log.Error("sending a message: the answer holds no message",
+				"content_type", item.Content.Type)
+			h.respondError(w, http.StatusInternalServerError,
+				"the chat client's answer could not be read")
+
+			return
+		}
+
+		h.respond(w, http.StatusCreated, response{Message: sent})
+	}
+}
+
+// respondChatError answers a request the chat client did not serve: 404
+// for a chat the bot does not have, 409 for a contact who cannot receive
+// messages, 413 for a text too long to send, and 500 with sentence for
+// anything else, which is logged as what.
+func (h *handlers) respondChatError(
+	w http.ResponseWriter, err error, what, sentence string,
+) {
+	switch {
+	case errors.Is(err, simplex.ErrNoContact):
+		h.respondError(w, http.StatusNotFound, noSuchChat)
+	case errors.Is(err, simplex.ErrContactNotReady):
+		h.respondError(w, http.StatusConflict, "the contact cannot receive messages")
+	case errors.Is(err, simplex.ErrMessageTooLarge):
+		h.respondError(w, http.StatusRequestEntityTooLarge, "the text is too long")
+	default:
+		h.log.Error(what, "error", err)
+		h.respondError(w, http.StatusInternalServerError, sentence)
+	}
+}
+
+// chatID returns the chat id in the request's path, and false if it is
+// not one: a chat's id is its contact's, a positive whole number.
+func chatID(r *http.Request) (int64, bool) {
+	id, err := strconv.ParseInt(chi.URLParam(r, "id"), 10, 64)
+
+	return id, err == nil && id > 0
+}
+
+// messageCount returns the request's count, defaultCount if it has none,
+// and false if it is anything but a whole number from 1 to maxCount. The
+// query is parsed here because r.URL.Query drops a pair it cannot
+// decode, which would turn count=1% into the default.
+func messageCount(r *http.Request) (int, bool) {
+	query, err := url.ParseQuery(r.URL.RawQuery)
+	if err != nil {
+		return 0, false
+	}
+
+	if !query.Has("count") {
+		return defaultCount, true
+	}
+
+	count, err := strconv.Atoi(query.Get("count"))
+
+	return count, err == nil && count >= 1 && count <= maxCount
+}

internal/api/messages_test.go

@@ -0,0 +1,309 @@
+package api_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/simplexcalc/internal/simplex"
+)
+
+// Answers more than one test expects.
+const (
+	noSuchChat = `{"error":"no such chat"}` + "\n"
+	badCount   = `{"error":"count must be a whole number from 1 to 100"}` + "\n"
+	notJSON    = `{"error":"the body must be JSON such as {\"text\":\"hello\"}"}` + "\n"
+)
+
+// chatItem is a chat item decoded from a record shaped as the chat
+// client sends it, reduced to the fields the API reads.
+func chatItem(t *testing.T, record string) simplex.ChatItem {
+	t.Helper()
+
+	var item simplex.ChatItem
+
+	err := json.Unmarshal([]byte(record), &item)
+	if err != nil {
+		t.Fatalf("decoding %s: %v", record, err)
+	}
+
+	return item
+}
+
+// post sends srv a POST of body to path, with the credential.
+func post(
+	t *testing.T, srv *http.Server, path, body string,
+) *httptest.ResponseRecorder {
+	t.Helper()
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodPost, path,
+		strings.NewReader(body))
+	req.Header.Set("Authorization", bearer)
+
+	rec := httptest.NewRecorder()
+	srv.Handler.ServeHTTP(rec, req)
+
+	return rec
+}
+
+// TestMessages: the messages among the chat's last 20 items come back
+// oldest first, without the events the chat client records in a chat,
+// and the chat client is asked with a deadline.
+func TestMessages(t *testing.T) {
+	t.Parallel()
+
+	client := &fakeClient{items: []simplex.ChatItem{
+		chatItem(t, `{"meta":{"itemId":7,"itemTs":"2026-09-29T03:13:46.521359978Z"},
+			"content":{"type":"rcvChatFeature","feature":"calls"}}`),
+		chatItem(t, `{"meta":{"itemId":9,"itemTs":"2026-09-29T03:14:34Z"},
+			"content":{"type":"rcvMsgContent",
+			"msgContent":{"type":"text","text":"2 + 2"}}}`),
+		chatItem(t, `{"meta":{"itemId":10,"itemTs":"2026-09-29T03:14:35.101Z"},
+			"content":{"type":"sndMsgContent","msgContent":{"type":"text","text":"4"}}}`),
+		chatItem(t, `{"meta":{"itemId":11,"itemTs":"2026-09-29T03:15:02Z"},
+			"content":{"type":"rcvMsgContent","msgContent":{"type":"image",
+			"text":"a picture","image":"data:image/jpg;base64,/9j/4AAQ"}}}`),
+	}}
+
+	rec := request(t, newAPI(credential, client), http.MethodGet, messagesPath, bearer)
+
+	want := `{"messages":[` +
+		`{"id":9,"direction":"received","type":"text","text":"2 + 2",` +
+		`"time":"2026-09-29T03:14:34Z"},` +
+		`{"id":10,"direction":"sent","type":"text","text":"4",` +
+		`"time":"2026-09-29T03:14:35.101Z"},` +
+		`{"id":11,"direction":"received","type":"image","text":"a picture",` +
+		`"time":"2026-09-29T03:15:02Z"}]}` + "\n"
+	if rec.Code != http.StatusOK || rec.Body.String() != want {
+		t.Errorf("response = %d %q, want 200 %q", rec.Code, rec.Body.String(), want)
+	}
+
+	if client.contactID != 3 || client.count != 20 || !client.hadDeadline {
+		t.Errorf("the chat client was asked for %d items of chat %d, deadline %v; "+
+			"want 20 of chat 3 with a deadline",
+			client.count, client.contactID, client.hadDeadline)
+	}
+}
+
+// TestNoMessages: a chat without messages is an empty list, not null.
+func TestNoMessages(t *testing.T) {
+	t.Parallel()
+
+	rec := request(t, newAPI(credential, &fakeClient{}),
+		http.MethodGet, messagesPath, bearer)
+
+	want := `{"messages":[]}` + "\n"
+	if rec.Code != http.StatusOK || rec.Body.String() != want {
+		t.Errorf("response = %d %q, want 200 %q", rec.Code, rec.Body.String(), want)
+	}
+}
+
+// TestMessagesCount: count is a whole number from 1 to 100, and 20 when
+// absent. Anything else is refused before the chat client is asked.
+func TestMessagesCount(t *testing.T) {
+	t.Parallel()
+
+	// The number of items the chat client is asked for; 0 for refused.
+	for query, want := range map[string]int{
+		"":           20,
+		"?count=1":   1,
+		"?count=100": 100,
+		"?count=%35": 5,
+		"?count=0":   0,
+		"?count=101": 0,
+		"?count=-1":  0,
+		"?count=2.5": 0,
+		"?count=ten": 0,
+		"?count=":    0,
+		"?count=1%":  0,
+	} {
+		t.Run(query, func(t *testing.T) {
+			t.Parallel()
+
+			client := &fakeClient{}
+			rec := request(t, newAPI(credential, client),
+				http.MethodGet, messagesPath+query, bearer)
+
+			if want == 0 {
+				if rec.Code != http.StatusBadRequest || rec.Body.String() != badCount ||
+					client.count != 0 {
+					t.Errorf("response = %d %q, asked for %d items; "+
+						"want 400 %q and nothing asked", rec.Code, rec.Body.String(),
+						client.count, badCount)
+				}
+
+				return
+			}
+
+			if rec.Code != http.StatusOK || client.count != want {
+				t.Errorf("response = %d, asked for %d items; want 200 and %d",
+					rec.Code, client.count, want)
+			}
+		})
+	}
+}
+
+// TestNoSuchChat: a chat id that is not a positive whole number gets 404
+// without asking the chat client, and so does one it has no contact
+// for, whether reading messages or sending one.
+func TestNoSuchChat(t *testing.T) {
+	t.Parallel()
+
+	for _, id := range []string{"tester", "0", "-3", "3.5", "99999999999999999999"} {
+		client := &fakeClient{}
+		srv := newAPI(credential, client)
+		path := "/api/v1/chats/" + id + "/messages"
+
+		for _, rec := range []*httptest.ResponseRecorder{
+			request(t, srv, http.MethodGet, path, bearer),
+			post(t, srv, path, `{"text":"hello"}`),
+		} {
+			if rec.Code != http.StatusNotFound || rec.Body.String() != noSuchChat {
+				t.Errorf("chat %q: response = %d %q, want 404 %q",
+					id, rec.Code, rec.Body.String(), noSuchChat)
+			}
+		}
+
+		if client.contactID != 0 {
+			t.Errorf("chat %q: the chat client was asked", id)
+		}
+	}
+
+	srv := newAPI(credential, &fakeClient{err: simplex.ErrNoContact})
+
+	for _, rec := range []*httptest.ResponseRecorder{
+		request(t, srv, http.MethodGet, messagesPath, bearer),
+		post(t, srv, messagesPath, `{"text":"hello"}`),
+	} {
+		if rec.Code != http.StatusNotFound || rec.Body.String() != noSuchChat {
+			t.Errorf("no contact: response = %d %q, want 404 %q",
+				rec.Code, rec.Body.String(), noSuchChat)
+		}
+	}
+}
+
+// TestMessagesFailure: when the chat client fails, the answer says so in
+// a chosen sentence, never in the error's own text.
+func TestMessagesFailure(t *testing.T) {
+	t.Parallel()
+
+	rec := request(t, newAPI(credential, &fakeClient{err: errChat}),
+		http.MethodGet, messagesPath, bearer)
+
+	want := `{"error":"the messages could not be read"}` + "\n"
+	if rec.Code != http.StatusInternalServerError || rec.Body.String() != want {
+		t.Errorf("response = %d %q, want 500 %q", rec.Code, rec.Body.String(), want)
+	}
+}
+
+// TestSend: the text goes to the chat's contact, with a deadline, and
+// the answer is 201 with the message as sent.
+func TestSend(t *testing.T) {
+	t.Parallel()
+
+	client := &fakeClient{sent: chatItem(t, `{"meta":{"itemId":12,
+		"itemTs":"2026-09-29T03:14:43.519552587Z"},"content":{"type":"sndMsgContent",
+		"msgContent":{"type":"text","text":"hello"}}}`)}
+
+	rec := post(t, newAPI(credential, client), messagesPath, `{"text":"hello"}`)
+
+	want := `{"message":{"id":12,"direction":"sent","type":"text","text":"hello",` +
+		`"time":"2026-09-29T03:14:43.519552587Z"}}` + "\n"
+	if rec.Code != http.StatusCreated || rec.Body.String() != want {
+		t.Errorf("response = %d %q, want 201 %q", rec.Code, rec.Body.String(), want)
+	}
+
+	if client.contactID != 3 || client.text != "hello" || !client.hadDeadline {
+		t.Errorf("the chat client was asked to send %q to chat %d, deadline %v; "+
+			`want "hello" to chat 3 with a deadline`,
+			client.text, client.contactID, client.hadDeadline)
+	}
+}
+
+// TestSendBadBody: a body that is not JSON with a text, or that is over
+// 64 KiB, is refused before anything is sent.
+func TestSendBadBody(t *testing.T) {
+	t.Parallel()
+
+	textEmpty := `{"error":"text is empty"}` + "\n"
+	tooLarge := `{"error":"the body is too large"}` + "\n"
+
+	for name, tc := range map[string]struct {
+		body   string
+		status int
+		answer string
+	}{
+		"empty":             {"", http.StatusBadRequest, notJSON},
+		"not JSON":          {"hello", http.StatusBadRequest, notJSON},
+		"not an object":     {`["hello"]`, http.StatusBadRequest, notJSON},
+		"text not a string": {`{"text":5}`, http.StatusBadRequest, notJSON},
+		"more after it":     {`{"text":"hello"} {}`, http.StatusBadRequest, notJSON},
+		"no text":           {`{}`, http.StatusBadRequest, textEmpty},
+		"empty text":        {`{"text":""}`, http.StatusBadRequest, textEmpty},
+		"over 64 KiB": {
+			`{"text":"` + strings.Repeat("a", 64<<10) + `"}`,
+			http.StatusRequestEntityTooLarge, tooLarge,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			client := &fakeClient{}
+			rec := post(t, newAPI(credential, client), messagesPath, tc.body)
+
+			if rec.Code != tc.status || rec.Body.String() != tc.answer {
+				t.Errorf("response = %d %q, want %d %q",
+					rec.Code, rec.Body.String(), tc.status, tc.answer)
+			}
+
+			if client.contactID != 0 {
+				t.Error("the chat client was asked to send")
+			}
+		})
+	}
+}
+
+// TestSendRefused: a send the chat client refuses, or answers with no
+// message, gets an answer chosen for the reason, never the chat
+// client's own words.
+func TestSendRefused(t *testing.T) {
+	t.Parallel()
+
+	for name, tc := range map[string]struct {
+		client *fakeClient
+		status int
+		answer string
+	}{
+		"contact deleted": {
+			&fakeClient{err: simplex.ErrContactNotReady},
+			http.StatusConflict, `{"error":"the contact cannot receive messages"}`,
+		},
+		"text too long": {
+			&fakeClient{err: simplex.ErrMessageTooLarge},
+			http.StatusRequestEntityTooLarge, `{"error":"the text is too long"}`,
+		},
+		"anything else": {
+			&fakeClient{err: errChat},
+			http.StatusInternalServerError, `{"error":"the message could not be sent"}`,
+		},
+		"no message in the answer": {
+			&fakeClient{sent: chatItem(t, `{"meta":{"itemId":13},
+				"content":{"type":"sndDirectEvent"}}`)},
+			http.StatusInternalServerError,
+			`{"error":"the chat client's answer could not be read"}`,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			rec := post(t, newAPI(credential, tc.client), messagesPath, `{"text":"hello"}`)
+
+			if rec.Code != tc.status || rec.Body.String() != tc.answer+"\n" {
+				t.Errorf("response = %d %q, want %d %q",
+					rec.Code, rec.Body.String(), tc.status, tc.answer)
+			}
+		})
+	}
+}