Arandu Integrations

Other systems

When to use

A call that leaves the process, a request another system sends in, or a capability handed to an assistant. The service that decides to make the call is arandu-module; the job or listener that makes it later is arandu-async.

Before you start

• Read the example's client: app/Clients/NewsletterClient.go, its fake app/Clients/NewsletterFake.go, the service that depends on it (NoteService.SendDigest) and newsletter at the end of bootstrap/app.go.
• Read the example's received webhook: NewsletterWebhookController.Store, NewsletterEventService.Receive, the /webhooks/newsletter route and the middleware.CSRFExcept("/webhooks/") passed to CSRFProtect in bootstrap/app.go.
• Ask arandu-ecosystem first whether the client belongs here at all: a client another project would reuse, and an engine that wraps another technology -- a model runtime, OCR, a camera -- is a github.com/hyz-is/arandu-* module.

Contracts and imports

Procedure

1. Generate the client: aru make:client Newsletter writes the config, the interface, the client, the fake and a test that runs the client against a faked factory. Add each call to the interface, the client and the fake together, in their custom blocks, with types of the client's own so no caller reads the vendor's wire format.
2. Make the call idempotent when it changes something on the other side: carry a key that survives a retry, as NewsletterDigest.Key does, sent as Idempotency-Key.
3. Depend on the interface. The service takes clients.Newsletter, set with WithNewsletter; bootstrap/app.go builds the real client from the configuration, or leaves it nil when nothing is configured, so the application runs with no credential and a test passes the fake.
4. Receive a webhook under /webhooks/<vendor>, in a controller that reads the raw body, verifies the signature and the timestamp before anything else, binds the request from the same bytes, hands it to a service and answers 2xx. The service records the delivery -- the example stores an event in the outbox under the delivery id, which the relay hands to the listeners after the answer -- so a slow step never times the sender out. Work that needs retries is a job a listener of that event dispatches, never one the service dispatches: the job's package imports app/Services.
5. Expose a capability to an assistant with aru make:mcp-tool ShowNote --service=Note (make:mcp-resource, make:mcp-prompt for the other two kinds). It writes the type in app/Mcp, its test and the wiring; the module is taken first with go get github.com/arandu-io/mcp@v0.4.0.

Commands

• aru make:client <Vendor>
• aru make:mcp-tool <Name> --service=<Entity>, aru make:mcp-resource <Name> --service=<Entity>, aru make:mcp-prompt <Name>

Example

Code that calls an external system, and the two stand-ins a test builds for it -- neither reaches the network:

package example

import (
	"context"
	"net/http"

	"github.com/arandu-io/hesape/http/client"

	clients "<module>/app/Clients"
)

// Announce takes the client's interface, never the concrete type, so a test
// hands it the fake.
func Announce(ctx context.Context, newsletter clients.Newsletter, title string) error {
	return newsletter.SendDigest(ctx, clients.NewsletterDigest{
		Key:   "announce-" + title,
		Notes: []clients.NewsletterNote{{Title: title}},
	})
}

// Offline builds the fake, which records the call, and the real client over a
// faked factory, which records the request it would have sent.
func Offline() (*clients.NewsletterFake, *clients.NewsletterClient) {
	fake := &clients.NewsletterFake{}
	factory := client.NewFactory(nil).Fake(func(*http.Request) (*http.Response, error) {
		return client.NewResponseFromBytes(http.StatusAccepted, nil, nil).HTTPResponse(), nil
	})
	faked := clients.NewNewsletterClient(clients.NewsletterConfig{BaseURL: "https://newsletter.example.test"}, factory)
	return fake, faked
}

A received webhook, reduced to its order: the signature over the exact bytes, then the request, then the service, then 202 -- as NewsletterWebhookController.Store does it:

package example

import (
	"bytes"
	"io"
	"net/http"

	"github.com/arandu-io/hesape/exception"
	hhttp "github.com/arandu-io/hesape/http"
	"github.com/arandu-io/hesape/webhook"

	requests "<module>/app/Http/Requests"
	services "<module>/app/Services"
)

// Receive refuses a delivery whose signature does not verify before it reads
// a single field of it.
func Receive(ctx *hhttp.Context, secrets webhook.SecretSet, events *services.NewsletterEventService) error {
	body, err := io.ReadAll(ctx.Request.Body)
	if err != nil {
		return err
	}
	delivery := ctx.Header("X-Arandu-Delivery-ID")
	if !webhook.Verify(secrets, ctx.Header("X-Arandu-Timestamp"), delivery, body, ctx.Header("X-Arandu-Signature")) {
		return exception.Abort(http.StatusUnauthorized, "this delivery is not signed by the provider")
	}
	ctx.Request.Body = io.NopCloser(bytes.NewReader(body))
	var in requests.NewsletterEventRequest
	if err := ctx.Bind(&in); err != nil {
		return err
	}
	if err := events.Receive(ctx.Ctx(), delivery, in); err != nil {
		return err
	}
	return ctx.Status(http.StatusAccepted)
}

The controller also refuses a timestamp more than five minutes from its clock, which this reduction leaves out: the signature covers the timestamp, so a captured delivery replayed later is refused even though it still verifies.

An MCP tool, as aru make:mcp-tool ShowNote --service=Note writes it. It is not compiled here, because this project does not require the mcp module:

func (t ShowNote) Handle(ctx context.Context, r mcp.Request) (mcp.Response, error) {
	id, _ := r.String("id")
	found, err := t.svc.Get(ctx, r.Subject(), id)
	if err != nil {
		return mcp.Response{}, err
	}
	return mcp.JSON(resources.NewNoteResource(found)), nil
}