aicoded.dev

Page calls: functions a page's script calls

A page call lets the page's script ask its server for something without a reload or a separate API. The page declares the call with typed arguments and result, the data provider answers it, and the access rules and Guards of the page run again before every call.

Declaring a call

<!-- pages/notes/n_id/index.html -->
<ssr:access role="*" guard="true"/>
<ssr:var name="note" type="Note"/>
<ssr:call name="star" in="StarIn" out="StarOut"/>
<h1>{{ note.Title }}</h1>
<button id="star" type="button">Star</button>
<p id="star-result"></p>

The types travel as JSON, with the names encoding/json gives them, so give their fields json tags:

// pages/notes/n_id/types.go

// StarIn is what the page sends to star a note.
type StarIn struct {
	Starred bool `json:"starred"`
}

// StarOut is what the page gets back.
type StarOut struct {
	Starred bool   `json:"starred"`
	Title   string `json:"title"`
}

Answering it

aicoded generate adds Call<Name> to the page's data provider. Its stub refuses every call with 403 until you write it:

// CallStar stars or unstars the note. The page's Guard has checked the owner for this call.
func (p *DP) CallStar(ctx context.Context, r *web.Request, in StarIn) (StarOut, error) {
	n, err := p.d.Note(ctx, r.URLParamInt("id"))
	if err != nil {
		return StarOut{}, err
	}
	if err := p.d.Star(ctx, n.ID, in.Starred); err != nil {
		return StarOut{}, err
	}
	return StarOut{Starred: in.Starred, Title: n.Title}, nil
}

Calling it from the script

index.ts next to the template imports the page's generated reactive_gen.ts:

import { ssr, type CallError } from "./reactive_gen";

const out = document.getElementById("star-result");
document.getElementById("star")?.addEventListener("click", () => {
  ssr
    .call("star", { starred: true })
    .then((r) => {
      if (out) out.textContent = `Starred ${r.title}.`;
    })
    .catch((e: CallError) => {
      if (out) out.textContent = e.message;
    });
});

ssr.call returns a promise of the result, typed from StarOut, and rejects with a CallError, {status, message}:

The call status message
returns web.Error(status, message), web.Forbidden() or web.NotFound() its status its message
fails a page's access rule or Guard 403, or what the Guard returned the error's message
names a call that the open page does not have 404 "This call is not on this page."
takes longer than 30 seconds 504 "The call took too long."
has wrong arguments 400 "The call has the wrong arguments."
is the fifth at once of this page 429 "Too many calls at once."
returns web.Redirect (E-WEB-005), another error, or panics 500 "Something went wrong.", and the error is logged
was sent when the connection dropped 0 "The connection was lost."

In the permission list

aicoded generate lists each page's calls, and those of the layouts it is shown in, under calls in the page's entry of the access section of the permission list:

access:
  "/notes/{id}":
    require: ["*"]
    guard: true
    calls: ["star"]

See also

Markdown · Source on GitHub · framework f46741f