Cara kerjanya

Lambda adalah snippet yang mengembalikan handler GenHTTP. Platform mengompilasinya, memuatnya, lalu memasang apa pun yang dikembalikannya di bawah alamat Anda sendiri. Tidak ada proyek, tidak ada file build, dan tidak ada statement using. Semua modul GenHTTP sudah di-import untuk Anda.

return Content.From(Resource.FromString("hello"));

Itu sudah lambda yang lengkap. Setelah di-deploy di /lambda/your-key/, lambda ini menjawab setiap request dengan kata hello.

Snippet ini berisi statement, bukan class. Hal terakhir yang dilakukannya adalah mengembalikan sesuatu yang bisa melayani request: handler, atau builder untuk handler.

1. 1
   Tekan Buat lambda. Anda mendapat alamat publik dan kunci editor. Kunci itu satu-satunya jalan untuk masuk lagi, jadi simpan baik-baik. Tidak ada yang bisa memulihkannya untuk Anda.
2. 2
   Anda masuk ke pusat kontrolnya, dengan layanan REST kecil yang sudah tertulis sebagai versi pertama. Itu hanya titik awal.
3. 3
   Berikan kunci editor ke agen dan jelaskan apa yang harus dibuat. Agen menulis versi-versi baru lewat MCP. Atau buka Kode dan tulis sendiri: Periksa mengompilasi tanpa menyimpan apa pun, lalu menunjukkan pesan compiler, lengkap dengan file dan barisnya.
4. 4
   Tekan Deploy. Sekarang lambda Anda online. Sebelum itu, tidak ada yang bisa diakses. Deploy ulang memperpanjang masa online-nya.

Link editor membuka pusat kontrol, bukan kotak teks. Sebagian besar kode di sini ditulis oleh agen, jadi yang pertama tampil di layar adalah kondisi lambda Anda. Sidebar berisi lambda-nya (apakah online, alamatnya, dan tombol kalau ada versi lebih baru yang menunggu untuk online) beserta bagian-bagiannya. Hal yang jarang dilakukan, seperti mengganti alamat atau menghapus lambda, ada di menu ⋯ di sana.

Ringkasan

Apa aplikasinya, apakah lambda online, berapa request hari ini dan berapa yang gagal, perubahan terakhir, dan sisa ruang penyimpanan.

Dokumentasi

Apa aplikasinya, untuk siapa dan mengapa, dan mengapa aplikasi dibuat seperti itu - ditulis oleh agen, disimpan bersama setiap versi.

Ubah

Tulis apa yang perlu diubah, dan agen di server ini akan mengerjakannya sementara Anda melihat. Agen mencoba perubahan itu di sebuah draf - salinan dengan alamatnya sendiri - lalu menjadikannya online begitu berhasil. Matikan Langsung online setelah selesai kalau Anda ingin mencoba drafnya sendiri dulu. Agen hanya mengerjakan aplikasi Anda: permintaan yang tidak berkaitan dengannya, atau yang bertujuan merugikan, akan ditolak beserta alasannya.

Draf

Perubahan yang dicoba sebelum dijadikan online, masing-masing di alamat sendiri dan dengan data uji sendiri. Saat dibuka, draf punya kode, data uji, dan log-nya sendiri. Bagian ini muncul setelah ada draf.

File

File dari sebuah versi: kode dan asetnya, yaitu programnya sendiri. Ikon gembok atau globe menunjukkan apakah publik bisa mengaksesnya.

Data

Apa yang disimpan lambda selama berjalan, dipakai bersama oleh semua versi: database, workspace, dan kunci dan kata sandi, masing-masing di tab sendiri. Lihat tabel dan file, unggah file, atur kunci dan kata sandi, atau aktifkan dan nonaktifkan suatu jenis. Tampilan sederhana menampilkannya begitu aplikasi menyimpan sesuatu.

Versi

Apa yang diubah setiap versi dan apa yang diminta, serta bedanya dengan versi sebelumnya. Deploy atau rollback dari sini, atau mulai draf dari versi mana pun.

Deployment

Apa yang online dan kapan, dan apa yang membuatnya berhenti.

Statistik

Request, kegagalan, waktu respons, dan path yang paling sering diminta, selama satu jam atau satu hari terakhir.

Log

Request yang masuk, apa yang dicetak lambda, dan stack trace dari setiap error, secara langsung.

Kode

Menulis kode secara manual. Periksa mengompilasi, Simpan membuat versi, Deploy menjadikannya online. Di draf, Simpan menyimpannya di draf dan menampilkannya di alamat draf itu.Ctrl-S menyimpan; F12 membuka deklarasi.

Pengujian

Bagaimana aplikasi diuji secara otomatis, dengan script dan data uji untuk itu. Hanya di tampilan lengkap.

Setiap bagian bekerja dengan cara yang sama: judulnya, tombol ⓘ yang menjelaskannya, aksinya di kanan, dan (kalau punya lebih dari satu tampilan) deretan tab di bawahnya. Tab di bagian kode adalah file-filenya. Tampilan lengkap mengelompokkan bagian-bagiannya: cara orang menemukannya, tempat perubahan dibuat, program dan datanya, dan cara berjalannya.

Trafik dan log hanya ada di memori, untuk dipantau, bukan untuk diarsipkan: restart server memulainya dari awal. Versi dan riwayat deployment disimpan permanen.

Sebuah versi berisi kode, plus dua catatan opsional: spesifikasi, yaitu apa yang diinginkan pengguna dan alasannya, sebisa mungkin dengan kata-kata mereka sendiri, dan perubahan, satu baris tentang apa yang dilakukan versi itu. Keduanya ditampilkan di samping diff di riwayat versi, jadi alasannya tetap tercatat di samping isinya. Berguna untuk Anda, dan untuk agen berikutnya yang membaca riwayat sebelum mengubah apa pun.

POST /api/v1/lambdas/{editorKey}/versions
{
  "files": [ { "name": "lambda.cs", "code": "..." } ],
  "specification": "Buku tamu yang bisa diisi orang; entri harus tetap ada setelah restart",
  "change": "Menyimpan entri di database supaya tetap ada setelah restart"
}

Agen mengirim dua field yang sama ke write_code. Di Kode, saat menyimpan Anda diminta mengisi perubahannya. Keduanya opsional. Spesifikasi yang terlalu panjang dipotong di 4.000 karakter, dan perubahan di 500 karakter, bukan ditolak. Draf menyimpan dua catatannya sendiri, dan versi hasil penggabungannya mengambil alih catatan itu.

Setiap versi menyimpan apa yang ditulis tentangnya di samping programnya: dokumentasinya (apa aplikasinya, untuk siapa dan mengapa, dan mengapa aplikasi dibuat seperti itu) dan pengujiannya: cara memeriksa secara otomatis bahwa aplikasi berfungsi, dengan script dan data uji untuk itu. Agen menulis keduanya bersama lambda baru dan memperbaruinya di setiap perubahan. Agen berikutnya yang mengubah lambda membacanya lebih dulu, sehingga tahu untuk apa aplikasi itu dan apa yang harus tetap berfungsi - hal yang tidak bisa diketahui dari kodenya saja.

.lambda/docs/product.md

apa aplikasinya, untuk siapa, apa yang dilakukan orang dengannya, dan mengapa

.lambda/docs/decisions.md

keputusan teknis, dan alasan keputusan itu diambil

.lambda/tests/README.md

bagaimana aplikasi diuji secara otomatis, dan cara menjalankan pengujiannya

.lambda/tests/…

script dan data uji yang dipakai pengujian

Keduanya adalah file versi seperti file lainnya, di folder .lambda: riwayat menunjukkan apa yang diubah sebuah versi di dalamnya, rollback mengembalikan dokumentasi yang berlaku untuk versi itu, dan draf punya salinannya sendiri yang ikut online bersamanya. Keduanya tidak pernah dikompilasi dan tidak pernah disajikan, dan dihitung dalam batas ukuran aset sebuah versi.

Di pusat kontrol, Dokumentasi menampilkan halaman untuk dibaca, dan Pengujian menampilkan cara aplikasi diuji beserta file di sampingnya; versinya dipilih seperti untuk file-filenya. Halaman juga bisa diedit di sana, yang akan menyimpan versi berikutnya. Tampilan sederhana menyebut dokumentasi Tentang dan hanya menampilkan untuk apa aplikasi itu. Untuk memperbaikinya, sampaikan kepada agen.

Keduanya ditulis dalam bahasa yang Anda pakai dengan agen, untuk siapa pun yang mengubah aplikasi berikutnya - manusia atau agen. Bukan salinan kode, melainkan untuk apa aplikasi itu, dan mengapa.

Versi tidak pernah berubah setelah disimpan, dan justru itulah yang membuat setiap versi layak disimpan: versi mana pun bisa dibandingkan, dan dijadikan online lagi persis seperti semula. Untuk mengubah lambda yang sedang dipakai orang, coba dulu perubahannya di draf.

1. 1
   Mulai dari versi mana pun di Versi, atau biarkan agen memulainya. Draf adalah salinan kode, aset, dokumentasi, dan pengujian versi itu, serta salinan data lambda.
2. 2
   Ubah sesering yang diperlukan, di Kode atau dengan meminta agen. Pratinjaunya menjawab di alamatnya sendiri, /features/…/, dengan data uji miliknya sendiri. Pengunjung lambda tidak melihat apa pun, dan tidak ada yang ditulisnya yang sampai ke data lambda.
3. 3
   Jadikan online setelah hasilnya pas: draf menjadi versi berikutnya, lengkap dengan catatannya, dan langsung online. Drafnya ikut hilang - termasuk pratinjau dan data ujinya.

POST /api/v1/lambdas/{editorKey}/features
{ "name": "Papan peringkat" }

PUT  /api/v1/lambdas/{editorKey}/features/{feature}/files?deploy=true
POST /api/v1/lambdas/{editorKey}/features/{feature}/merge
{ "deploy": true }

Beberapa draf bisa dikerjakan sekaligus. Hanya draf yang sudah terbaru dengan versi terbaru yang bisa dijadikan online, supaya tidak pernah membatalkan versi yang disimpan setelah draf dimulai. Jika draf lain lebih dulu online, masukkan perubahannya - atau minta agen melakukannya - lalu tandai draf sebagai sudah terbaru. Tidak ada yang online dengan sendirinya; itu disengaja. API menyebut draf sebagai feature, dan menjadikannya online sebagai merge.

Tipe tidak harus berada di bawah kode yang memakainya. Di Kode, tekan + di samping daftar file, dan file baru itu dikompilasi bersama snippet, di namespace yang sama, jadi tidak perlu import apa pun untuk mengaksesnya. Nama tanpa ekstensi dianggap C#.

var shelf = new Shelf();

return Inline.Create()
             .Get(() => shelf.All())
             .Post((Book book) => shelf.Add(book));

public sealed class Shelf
{
    private readonly List<Book> _books = [];

    public IEnumerable<Book> All() => _books;

    public Book Add(Book book)
    {
        _books.Add(book);
        return book;
    }
}

public record Book(string Title, string Author);

Ada dua cara untuk menyajikan halaman, dan satu cara lagi untuk file yang diunggah orang di sampingnya.

Satu halaman, ditulis inline

Cocok untuk yang kecil. Halamannya jadi bagian dari snippet.

var page = Resource.FromString("""
                              <!doctype html>
                              <title>Mine</title>
                              <h1>It works</h1>
                              """)
                   .Type(new ContentType("text/html; charset=utf-8"));

return Content.From(page);

Folder berisi file sungguhan

Pilihan tepat untuk apa pun yang punya stylesheet dan script. File ditambahkan dengan cara yang sama seperti file C#, dan disajikan persis seperti yang ditulis. Tidak ada yang mengompilasinya.

return Layout.Create()
             .Add("api", api)
             .Add(Assets.App("site"));

File unggahan, dari data

Untuk apa yang diunggah orang atau dibuat lambda (gambar, dokumen), disajikan di samping aplikasinya. Bukan untuk halaman aplikasinya sendiri: halaman itu tempatnya di folder file, di mana halaman ikut masuk versi bersama kode yang membutuhkannya.

return Layout.Create()
             .Add("api", api)
             .Add("uploads", Workspace.Files("uploads"))
             .Add(Assets.App("site"));

Cara kedua, secara lengkap. Setiap demo menyajikan halamannya dengan cara ini, dari folder bernama web. Buka demo-crud untuk melihat contohnya. Demo hanya bisa dibaca; kunci editornya adalah namanya sendiri.

1. 1
   Di Kode, tekan + di samping daftar file, lalu ketik site/index.html. Nama dengan garis miring menaruh file di dalam folder. Nama dengan ekstensi dianggap sebagai jenis file sesuai ekstensinya.
2. 2
   Tambahkan site/app.css dan site/app.js dengan cara yang sama. Halaman Anda merujuk keduanya dengan nama, seperti href="app.css", karena folder itu adalah root dari apa yang disajikan, bukan bagian dari alamat.
3. 3
   Untuk apa pun yang bukan teks, seperti gambar atau font, buka sebuah file di site, lalu tekan tombol unggah di samping daftar file. File itu akan masuk ke folder yang sama. PNG tidak bisa diketik di editor teks, jadi pakai tombol itu.
4. 4
   Di lambda.cs, sajikan foldernya:

   return Layout.Create().Add(Assets.App("site"));

5. 5
   Tekan Deploy. site/index.html menjawab di /, site/app.css di /app.css, dan alamat apa pun yang tidak cocok dengan file mana pun dijawab dengan halaman itu. Jadi front end yang mengatur routing sendiri tetap jalan saat seseorang me-reload halaman di deep link.
6. 6
   Tambahkan API di sampingnya, dan halaman itu punya lawan bicara:

   var api = Inline.Create().Get("notes", () => notes);
   
   return Layout.Create()
                .Add("api", api)
                .Add(Assets.App("site"));

Lambda menyimpan file di dua tempat, dan editor menampilkannya terpisah: File berisi file dari sebuah versi (programnya), dan Data berisi workspace (apa yang disimpan program itu). Bedanya ada di milik siapa. File dari sebuah versi milik versi itu; data milik lambda, dan dipakai bersama oleh semua versi.

Keduanya tidak bisa jadi satu tempat. Kalau jadi satu, deploy akan menghapus semua yang sudah ditulis lambda sejak deploy sebelumnya, atau tidak ada yang bisa dihapus dari file yang dibawanya. Game yang menyimpan papan peringkat butuh yang kedua; halaman yang disajikannya butuh yang pertama. Jadi halamannya masuk ke versi, dan papan peringkatnya ke data.

Catatan – entri, akun, pesanan, hasil voting – tempatnya di database: database SQLite milik lambda itu sendiri, yang diaktifkan di Data. Kode membuka koneksi dengan Database.GetConnection() lalu membaca dan menulis datanya melalui Entity Framework Core, dengan konteks miliknya sendiri yang memetakan tabel-tabelnya:

// migrations/V1__Create_notes.sql:
//   CREATE TABLE notes (id INTEGER PRIMARY KEY, text TEXT NOT NULL);

using (var connection = Database.GetConnection())
{
    new Evolve(connection) { Locations = [Assets.Root + "migrations"] }.Migrate();
}

return Inline.Create()
             .Get("notes", () =>
             {
                 using var db = new Notes(Database.GetConnection());

                 return db.Entries.OrderBy(n => n.Id).Select(n => n.Text).ToList();
             })
             .Post("notes", (NoteInput input) =>
             {
                 using var db = new Notes(Database.GetConnection());

                 db.Entries.Add(new Note { Text = input.Text });

                 return db.SaveChanges();
             });

record NoteInput(string Text);

class Note
{
    public long Id { get; set; }

    public string Text { get; set; }
}

// maps the table the migration made, on the connection it is handed
class Notes(SqliteConnection connection) : DbContext
{
    public DbSet<Note> Entries => Set<Note>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
        => options.UseSqlite(connection, contextOwnsConnection: true);

    protected override void OnModelCreating(ModelBuilder model)
        => model.Entity<Note>().ToTable("notes");
}

Tabelnya dibuat oleh migrasi: file SQL yang dibawa versi di migrations/, diterapkan berurutan oleh Evolve saat lambda dimulai – masing-masing sekali saja, jadi versi baru hanya menjalankan yang baru. Jangan pernah mengubah migrasi yang sudah diterapkan; perubahan pada tabel dibuat sebagai file berikutnya.

Seperti semua data, database dipakai bersama oleh semua versi, tidak disentuh oleh deploy maupun rollback, dan draf bekerja pada salinannya. Di Data Anda bisa melihat tabel dan isinya – tampilan sederhana menyebutnya catatan. Unduh sebagai proyek .NET menyertakannya sebagai file SQLite biasa.

Buat konteks di tempat Anda membutuhkannya, lalu dispose setelah selesai, dan pakai secara sinkron – ToList dan SaveChanges, bukan ToListAsync dan SaveChangesAsync. Tabel dibuat oleh migrasi, tidak pernah oleh Entity Framework. Demo demo-crud melakukan semua ini.

Workspace adalah direktori privat yang boleh dibaca dan ditulis lambda Anda: tempat untuk file – gambar yang diunggah seseorang, dokumen yang dibuatnya, model yang dimuatnya. Catatan tempatnya di database, dan apa yang diketahui tentang sebuah file – siapa yang mengunggahnya, kapan – juga termasuk catatan.

// uploads go into a folder of their own, served as they are
Workspace.CreateFolder("photos");

return Layout.Create()
             .Add("photos", Workspace.Files("photos"))
             .Add("upload", Inline.Create().Post(async (Stream body) =>
             {
                 using var content = new MemoryStream();

                 await body.CopyToAsync(content);

                 Workspace.WriteBytes($"photos/{Guid.NewGuid():N}.jpg", content.ToArray());
             }));

Ada juga ReadBytes, WriteBytes, Delete, List, CreateFolder, dan Tree/Files/App untuk menyajikannya. Selain itu, tidak ada bagian file system yang bisa diakses.

Kunci API, kata sandi, atau token tempatnya di rahasia, bukan di kode – di sana setiap versi, setiap unduhan, dan siapa pun yang membaca riwayatnya akan memilikinya. Kode membaca rahasia berdasarkan namanya:

var weather = new System.Net.Http.HttpClient();

weather.DefaultRequestHeaders.Add("X-Api-Key", Secret.Read("WEATHER_API_KEY"));

return Inline.Create()
             .Get("today", async () => await weather.GetStringAsync("https://weather.example/today"));

Aktifkan rahasia di Data dan atur nilainya di sana. Setelah disimpan, nilainya tidak pernah ditampilkan lagi – tidak kepada Anda, tidak kepada agen; Anda hanya bisa menggantinya. Daftarnya menunjukkan nama yang dibaca kode tetapi belum punya nilai, dan ikhtisar memintanya. Secret.Exists memberi tahu apakah rahasia sudah diatur, untuk kode yang tetap berjalan tanpanya. Seperti semua data, rahasia dipakai bersama oleh semua versi, dan draf bekerja pada salinannya.

Rahasia disimpan terenkripsi, dengan kunci yang tidak ada di database. Di proyek yang diunduh, Secret.Read("NAME") membaca variabel lingkungan NAME – nilainya sendiri tetap di sini.

Didukung, dan bukan sekadar tambahan. Demo demo-game memasangkan pemain dan menjalankan setiap permainan di server. Bentuk paling sederhananya berupa tiga callback:

var room = new ConcurrentDictionary<IReactiveConnection, string>();

var socket = Websocket.Functional()
                      .OnOpen(c => { room[c] = "someone"; return ValueTask.CompletedTask; })
                      .OnMessage(async (c, text) =>
                      {
                          foreach (var other in room.Keys)
                          {
                              await other.WritePayloadAsync(text);
                          }
                      })
                      .OnClose((c, _) => { room.TryRemove(c, out _); return ValueTask.CompletedTask; });

return Layout.Create().Add("chat", socket);

Jika halaman hanya mendengarkan (jumlah, umpan, papan skor), server-sent events lebih sederhana: satu respons panjang yang terus ditulis oleh server dan tersambung kembali dengan sendirinya oleh browser. Demo demo-live mengirim setiap suara kepada semua orang yang menonton dengan cara ini. Dengan cara mana pun, server mendorong apa yang berubah. Halaman yang bertanya lagi setiap beberapa detik mengirim request setiap kali, entah ada yang berubah atau tidak, dan tetap terlambat.

Satu hal yang sering menjebak: browser tidak bisa menambahkan header pada handshake websocket. Kirim yang dibutuhkan handler lewat query, yang dibacanya dari connection.Request.Header.Query, atau kirim data rahasia sebagai pesan pertama.

Kode Anda berjalan di server bersama, jadi sebagian C# ditolak sebelum dikompilasi: menjalankan proses, membuka socket sendiri, memuat assembly, mengakses file system di luar workspace Anda, dan reflection yang dipakai untuk mengakali semua itu. Begitu pula menunggu task dengan .Result atau .Wait() alih-alih await: request berjalan di satu thread per core, dan task tersebut harus selesai justru di thread yang sedang menunggunya.

Semua yang lain tersedia, termasuk seluruh API modul GenHTTP. Kalau ada yang ditolak, Anda diberi tahu baris mana dan alasannya, bukan sekadar pesan gagal.

Unduh sebagai proyek .NET di editor memberi Anda semuanya: solution yang bisa Anda buka, jalankan dengan dotnet run, dan simpan. Ia hanya membutuhkan paket GenHTTP, dan disertai Dockerfile untuk membangun dan menjalankannya sebagai container.

Snippet Anda menjadi Project.cs, dan Program.cs menyajikan apa yang dikembalikannya. File Anda yang lain ikut persis seperti yang Anda tulis. Workspace dan Assets menjadi dua folder di samping program, dengan method yang sama, terpisah di folder Platform, jadi tidak ada yang perlu diubah di kode Anda. Secret di sana membaca variabel lingkungan dengan nama yang sama; nilainya tetap di sini. Dokumentasi dan pengujian ikut serta di docs dan tests. Database membuka database/database.db, yang ikut terunduh bersama catatan yang disimpan aplikasi Anda.

Penting diketahui sebelum Anda membangun apa pun di sini: yang Anda tulis adalah milik Anda, dan bisa dibawa keluar utuh. Menjalankannya di server ini tidak membuatnya terkunci di server ini.

Kalau yang Anda buat bisa berguna bagi orang lain, publikasikan kodenya: buka Open Source di pusat kontrol, pilih lisensi - MIT, kecuali Anda menginginkan yang lain - lalu aktifkan. Kodenya mendapat halaman sendiri di antara aplikasi Open Source, tempat siapa pun bisa membacanya, memberinya bintang, dan mengunduh versi mana pun sebagai proyek yang sama dengan yang Anda dapat dari Unduh sebagai proyek .NET, lengkap dengan lisensinya.

Setiap versi dipublikasikan, termasuk yang lebih lama, beserta dokumentasi, pengujian, dan perubahan yang dibuat masing-masing. Apa yang disimpan aplikasi tidak pernah dipublikasikan - catatannya, file yang disimpannya, nilai kunci dan kata sandinya - begitu pula apa yang Anda minta dengan kata-kata Anda sendiri, atau siapa yang memakai aplikasinya. Nonaktifkan, dan halamannya hilang; bintangnya tetap disimpan untuk saat Anda memublikasikannya lagi.

Semua yang ada di kode menjadi publik, termasuk versi-versi sebelumnya. Kunci atau kata sandi tempatnya di kunci dan kata sandi di bagian Data, tidak pernah di kode - dipublikasikan atau tidak.

Ada endpoint MCP di /mcp. Arahkan agen ke sana, dan agen itu bisa melakukan semua yang bisa dilakukan editor: membaca panduan, membaca demo secara lengkap, menulis file, mengompilasinya, dan men-deploy. Di baliknya, API-nya sama.

Agen mencatat alasannya sambil bekerja (write_code menerima spesifikasi dan perubahan), dan bisa melihat apa yang sudah di-deploy-nya. read_logs menjawab dengan request terbaru lambda, apa yang dicetaknya, dan stack trace dari setiap exception. Dari situ agen tahu kodenya benar-benar jalan, bukan sekadar menebak. Anda memantau hal yang sama di pusat kontrol. Agen menulis dokumentasi dan pengujian sambil bekerja, membacanya sebelum mengubah apa pun, dan menjalankan pengujian terhadap alamat draf sebelum menjadikan draf itu online. Halaman yang dibuat untuk ditemukan orang diberi judul, deskripsi, ikon, dan pratinjau yang muncul saat link-nya dibagikan. Di bagian bawah halaman yang dibuatnya, agen menambahkan satu baris kecil yang menyatakan halaman itu dibuat dengan GenHTTP Lambda. Katakan kepadanya jika Anda tidak menginginkannya, lalu agen akan menghapusnya.

Selengkapnya →