In Part 2 you learned how to find elements on the page. In this article, you will put those locators to work by performing actions on them — clicking, typing, hovering, selecting, uploading files, and more.

You will also learn one of Playwright’s most important features: auto-waiting. Playwright does not blindly fire an action the moment you call it. It waits until the element is ready. This is why Playwright tests are far less flaky than tests written with older tools.

Auto-Waiting — Why You Rarely Need waitFor

Before covering individual actions, it is worth understanding what happens under the hood every time you call one.

When you write:

await page.getByRole('button', { name: 'Submit' }).click();

Playwright does not just fire a click immediately. It first checks that the element:

• Exists in the DOM
• Is visible (not hidden with display: none or visibility: hidden)
• Is stable (not animating or moving)
• Is enabled (not disabled)
• Is not obscured by another element

Only when all of those conditions are met does Playwright act. If the element is not ready yet, Playwright keeps retrying until the configured timeout is reached before failing.

This means you rarely need to write:

await page.waitForSelector('.submit-button'); // rarely needed
await page.waitForTimeout(2000);              // almost never needed

Just write the action. Playwright handles the waiting.

Clicking

click() is the most common action. It simulates a real mouse click — move, press, release.

// single click
await page.getByRole('button', { name: 'Submit' }).click();

// double click
await page.getByRole('button', { name: 'Edit' }).dblclick();

// right click (context menu)
await page.getByRole('listitem', { name: 'File' }).click({ button: 'right' });

// click a specific position within an element
await page.getByRole('canvas').click({ position: { x: 100, y: 200 } });

If the element is covered by an overlay like a cookie banner, Playwright will throw rather than silently clicking the wrong thing. Fix the root cause — dismiss the overlay first.

Typing and Filling Inputs

There are two ways to put text into an input: fill() and pressSequentially().

fill() — Use This First

fill() clears the current value and sets the new one in a single operation. It is fast and reliable.

await page.getByLabel('Email address').fill('user@example.com');
await page.getByLabel('Password').fill('secret123');

pressSequentially() — When You Need Key-by-Key Input

Some inputs respond to individual keystrokes — autocomplete dropdowns, for example. pressSequentially() types character by character, triggering keyboard events as it goes.

await page.getByLabel('Search').pressSequentially('play', { delay: 50 });

The delay option adds a pause between keystrokes in milliseconds. Without it the typing is instantaneous, which some inputs do not handle correctly.

clear() — Emptying a Field

await page.getByLabel('Username').clear();

press() — Single Key Presses

Use press() when you need to hit a specific key — Enter, Tab, Escape, or an arrow key.

await page.getByLabel('Search').press('Enter');
await page.getByRole('textbox').press('Tab');
await page.getByRole('dialog').press('Escape');

Key names follow the KeyboardEvent.key standard. Common ones:

Checkboxes and Radio Buttons

Use check() and uncheck() rather than click() for checkboxes and radio buttons. They are more explicit and Playwright verifies the resulting state.

// check a checkbox
await page.getByLabel('Remember me').check();

// uncheck it
await page.getByLabel('Remember me').uncheck();

// select a radio button
await page.getByLabel('Credit card').check();

To verify the current state:

await expect(page.getByLabel('Remember me')).toBeChecked();
await expect(page.getByLabel('Remember me')).not.toBeChecked();

Dropdowns — selectOption()

For a native <select> element, use selectOption().

// select by visible text
await page.getByLabel('Country').selectOption('United Kingdom');

// select by value attribute
await page.getByLabel('Country').selectOption({ value: 'uk' });

// select by index (zero-based)
await page.getByLabel('Country').selectOption({ index: 2 });

// select multiple options (if the select allows it)
await page.getByLabel('Interests').selectOption(['Music', 'Sport']);

Hovering

hover() moves the mouse over an element without clicking. Use it to trigger tooltips, reveal dropdown menus, or test hover states.

await page.getByRole('button', { name: 'More options' }).hover();

Focus and Blur

// move keyboard focus to an element
await page.getByLabel('Email').focus();

// remove focus
await page.getByLabel('Email').blur();

File Uploads

setInputFiles() sets files on an <input type="file"> element.

// upload a single file
await page.getByLabel('Upload document').setInputFiles('path/to/file.pdf');

// upload multiple files
await page.getByLabel('Upload photos').setInputFiles([
  'photo1.jpg',
  'photo2.jpg',
]);

// clear a previously selected file
await page.getByLabel('Upload document').setInputFiles([]);

For upload dialogs triggered by a button rather than a direct file input:

const [fileChooser] = await Promise.all([
  page.waitForEvent('filechooser'),
  page.getByRole('button', { name: 'Upload' }).click(),
]);
await fileChooser.setFiles('path/to/file.pdf');

Drag and Drop

await page.getByRole('listitem', { name: 'Task A' }).dragTo(
  page.getByRole('region', { name: 'Done' })
);

For fine-grained control:

await page.getByRole('slider').dragTo(
  page.getByRole('slider'),
  { targetPosition: { x: 200, y: 0 } }
);

Scrolling

Playwright scrolls automatically when it needs to bring an element into view before acting. For explicit scrolling:

// scroll an element into view
await page.getByRole('heading', { name: 'Pricing' }).scrollIntoViewIfNeeded();

// scroll the page by a pixel amount
await page.mouse.wheel(0, 500);

Summary

In Part 3, you learned how to interact with the page in a reliable way.

• Playwright waits for elements to be ready before it performs an action.
• fill() is the default choice for text inputs, while pressSequentially() is useful when key-by-key typing is required.
• check() and uncheck() are the right tools for checkboxes and radio buttons.
• selectOption() is used for native <select> dropdowns.
• press() lets you send single keys and key combinations such as Control+a.
• setInputFiles() works for file inputs, and the filechooser event pattern works for upload buttons.
• In most tests, you can skip manual waits like waitForTimeout.

What’s Next

In Part 4 you will learn assertions — how to verify that the right things appear on the page after your actions. Playwright’s web-first assertions retry automatically, and you will learn why that matters and how to use them correctly.

The post Part 3 — Actions and Auto-Waiting: Putting Locators to Work appeared first on Swacblooms🦋.

Before you can click a button, fill a form, or assert that something is visible, you need to tell Playwright which element you are talking about. That is what locators are for.

A locator is not just a selector — it is a smart reference to an element that re-queries the DOM every time you use it. This means if the page re-renders between steps, Playwright finds the fresh element automatically rather than holding a stale reference that no longer exists.

In this article, you will learn some of the most common locator methods Playwright provides, when to use each one, and the priority order the Playwright team recommends.

Recommended Built-in Locators

Playwright’s docs recommend these built-in locators over CSS and XPath because they are tied to what users actually see and interact with:

1. getByRole
2. getByText
3. getByLabel
4. getByPlaceholder
5. getByAltText
6. getByTitle
7. getByTestId

The guiding principle: the closer a locator is to how a real user perceives the page, the better. Users read text and interact with buttons and links — they do not think in CSS class names.

getByRole — Start Here

getByRole finds elements by their ARIA role and accessible name. This is the recommended first choice for almost every interactive element on the page.

// finds <a href="/docs/intro">Get started</a>
page.getByRole('link', { name: 'Get started' })

// finds <button>Submit</button>
page.getByRole('button', { name: 'Submit' })

// finds <h1>Installation</h1>
page.getByRole('heading', { name: 'Installation' })

// finds <input type="checkbox"> with label "Remember me"
page.getByRole('checkbox', { name: 'Remember me' })

The role comes from the HTML element itself — no aria-* attributes needed. The browser assigns roles automatically:

The accessible name comes from the element’s visible text content (as you saw in Part 1 with the Get started link). If the element has an aria-label or aria-labelledby, that takes priority over text content.

The name option accepts a string or a regular expression:

// exact string match
page.getByRole('button', { name: 'Sign in' })

// regex — useful when the text is dynamic
page.getByRole('button', { name: /sign in/i })

getByText — For Non-Interactive Elements

Use getByText when you want to find an element by its visible text content and there is no meaningful role to target — typically a <div>, <span>, or <p>.

// finds any element containing the text "Welcome back"
page.getByText('Welcome back')

// exact match only
page.getByText('Welcome back', { exact: true })

// regex
page.getByText(/welcome back/i)

Important: Playwright normalises whitespace automatically, even with { exact: true }. Multiple spaces become one, line breaks become spaces, and leading/trailing whitespace is ignored.

Avoid using getByText on buttons and links — use getByRole for those. getByText is for reading content, not for triggering actions.

getByLabel — For Form Fields

getByLabel finds an input by the text of its associated <label>. This is the right tool any time you are filling in a form.

// finds the input associated with <label>Email address</label>
page.getByLabel('Email address')

// usage in a test
await page.getByLabel('Email address').fill('user@example.com');
await page.getByLabel('Password').fill('secret');

The label association can be done two ways in HTML, and getByLabel handles both:

<!-- wrapping label -->
<label>
  Email address
  <input type="email" />
</label>

<!-- linked by for/id -->
<label for="email">Email address</label>
<input id="email" type="email" />

getByPlaceholder — When There Is No Label

Some inputs skip a visible label and rely on placeholder text instead. Use getByPlaceholder for those.

<input type="email" placeholder="Enter your email" />

await page.getByPlaceholder('Enter your email').fill('user@example.com');

Prefer getByLabel over getByPlaceholder when both are available — a visible label is better for accessibility and more stable as a test target.

getByAltText — For Images

getByAltText finds elements by their alt attribute. In practice this means images.

<img src="logo.png" alt="Company logo" />

await expect(page.getByAltText('Company logo')).toBeVisible();

getByTitle — For Title Attributes

getByTitle matches elements with a title attribute. Less common, but useful for icon buttons and tooltips that carry no visible text.

<button title="Close dialog">✕</button>

await page.getByTitle('Close dialog').click();

getByTestId — The Explicit Contract

getByTestId finds elements by a data-testid attribute (or a custom attribute you configure).

<button data-testid="submit-order">Place order</button>

await page.getByTestId('submit-order').click();

This locator is the most resilient to UI changes — the visible text and styling can change entirely without breaking your test. The trade-off: it requires you to add data-testid attributes to your HTML, and it is not based on anything a real user perceives.

Use it when:

• A role or text locator is not specific enough
• You want an explicit, stable contract between your tests and a specific element
• The element has no accessible role or visible text

You can configure a custom attribute name in playwright.config.js:

use: {
  testIdAttribute: 'data-cy', // use data-cy instead of data-testid
}

CSS and XPath — Last Resort

When none of the above fit, you can fall back to CSS selectors or XPath via locator().

// ID selector
page.locator('#submit-button')

// CSS selector
page.locator('.nav-menu > li:first-child')

// XPath
page.locator('//button[@type="submit"]')

Playwright auto-detects whether you passed CSS or XPath — no prefix needed.

Why avoid these? The DOM changes. Class names get renamed, elements get restructured, and your tests break for reasons unrelated to the actual behaviour of the app. The role and text-based locators are far more stable because they are tied to what users see, not to implementation details.

One additional limitation: XPath does not pierce Shadow DOM. All other Playwright locators work inside shadow roots by default.

Filtering Locators

When a locator matches more than one element, use filter() to narrow it down.

// all list items that contain the text "In stock"
page.getByRole('listitem').filter({ hasText: 'In stock' })

// list items that do NOT contain "Sold out"
page.getByRole('listitem').filter({ hasNotText: 'Sold out' })

// list items that contain a child button labelled "Add to cart"
page.getByRole('listitem').filter({
  has: page.getByRole('button', { name: 'Add to cart' })
})

Chaining Locators

All locator methods are also available on a locator itself, so you can scope a search inside a specific part of the page.

// find the navigation section first, then look for a link inside it
page.getByRole('navigation').getByRole('link', { name: 'Pricing' })

// find a form, then find the submit button inside it
page.getByRole('form', { name: 'Checkout' }).getByRole('button', { name: 'Place order' })

This is cleaner and more precise than a deeply nested CSS selector, and it reads like plain English.

Strictness — One Element at a Time

Playwright locators are strict by default. If a locator matches more than one element and you call an action on it (like .click()), Playwright throws an error rather than silently picking the first match.

Error: locator.click: Error: strict mode violation:
getByRole('button', { name: 'Submit' }) resolved to 2 elements

This is intentional — it forces you to write specific locators. The fix is to make the locator more precise rather than reaching for .first() or .nth(0):

// vague — which Submit button?
page.getByRole('button', { name: 'Submit' })

// specific — scoped to the checkout form
page.getByRole('form', { name: 'Checkout' }).getByRole('button', { name: 'Submit' })

Summary

Here is what you learned in Part 2:

• A locator re-queries the DOM every time it is used — no stale element references
• Use getByRole first: it targets elements the same way users and screen readers do
• Use getByLabel for form inputs, getByText for static content, getByAltText for images
• Use getByTestId when you need an explicit, stable testing contract
• Avoid CSS and XPath unless nothing else fits — they are tied to implementation details
• filter() and chaining let you narrow down locators precisely
• Locators are strict: if more than one element matches, Playwright errors rather than guessing

What’s Next

In Part 3 we put locators to work. You will learn some of the actions Playwright can perform — clicking, typing, hovering, selecting, uploading files — and how Playwright’s auto-waiting means you almost never need to add a manual wait.

The post Part 2 — Understanding Locators: Finding Things on the Page appeared first on Swacblooms🦋.

If you have ever shipped a feature that looked perfect in your local browser but broke immediately in production, you already understand why automated browser testing exists. Playwright is the answer to the question: “How do we make that kind of testing fast, reliable, and not painful to write?”

This first article walks you through what Playwright is, why it stands out from its competitors, how to install it, and how to read your very first test. By the end, you will have a working setup and a solid mental model of what each piece does.

What Is Playwright?

Playwright is an open-source end-to-end (E2E) testing framework built by Microsoft. “End-to-end” means it controls a real browser — Chrome, Firefox, or Safari — the same way a real user would: clicking links, filling forms, navigating pages, and checking that the right content appears.

Unlike unit tests (which test isolated functions) or integration tests (which test modules together), E2E tests validate the entire stack from the UI down to the database and back. They are the closest thing to “a human actually using your app.”

Playwright supports:

• Chromium (Chrome / Edge)
• Firefox
• WebKit (Safari)
• Mobile viewports
• Multiple languages: JavaScript, TypeScript, Python, Java, .NET

This series uses JavaScript/TypeScript.

Why Playwright?

There are other browser automation tools out there — Selenium and Cypress being the most well-known. This series focuses on Playwright, and here is what makes it worth your time:

• Supports all three major browser engines — Chromium, Firefox, and WebKit — out of the box
• Auto-waits for elements to be ready before acting, so no manual sleeps or brittle waits
• Runs tests in parallel across browsers simultaneously
• First-class TypeScript support with no extra configuration
• Built-in network interception, trace recording, and a visual debugger
• Actively maintained by Microsoft with frequent releases

Installing Playwright

Playwright requires Node.js 20.x, 22.x, or 24.x. Check your version:

node --version

To scaffold a new Playwright project, run:

npm init playwright@latest

The CLI will ask a few questions:

• TypeScript or JavaScript? (choose either — this series uses both)
• Where to put your tests? (default: tests/)
• Add a GitHub Actions workflow? (yes — we cover this in Part 11)
• Install Playwright browsers? (yes)

That last step downloads Chromium, Firefox, and WebKit — about 300 MB total. Playwright ships its own browser binaries, so your system browsers never interfere.

After installation, your project looks like this:

your-project/
├── node_modules/
├── tests/
│   └── example.spec.js       ← your starter test
├── playwright.config.js      ← all configuration lives here
├── package.json
└── package-lock.json

Your First Test — Line by Line

Open tests/example.spec.js. Here is what it contains:

// @ts-check
import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Let’s break each part down.

// @ts-check

A JSDoc comment that tells VS Code to type-check this plain JavaScript file using TypeScript’s engine. You get autocomplete and inline errors without needing a tsconfig. Optional, but useful.

import { test, expect } from '@playwright/test'

Two things are imported:

• test — the function you use to define a test case (like it() in Jest)
• expect — the assertion library (like Jest’s expect, extended with browser-aware matchers)

test('has title', async ({ page }) => { ... })

• The first argument is the test name — what shows up in the report.
• The second argument is an async function that receives fixtures. The page fixture is Playwright’s central object: it represents a single browser tab.
• Every browser interaction is async, so you use await throughout.

await page.goto('https://playwright.dev/')

Navigates the browser to a URL. Playwright waits for the page to reach a “load” state before moving on.

await expect(page).toHaveTitle(/Playwright/)

Asserts that the page’s <title> tag matches the regular expression /Playwright/. This is a web-first assertion — if the title is not there yet, Playwright retries the check for up to 5 seconds before failing. No manual waits needed.

await page.getByRole('link', { name: 'Get started' }).click()

Finds an <a> element whose accessible name is “Get started” and clicks it. getByRole is the preferred way to select elements — it mirrors how assistive technologies see your page and is far more resilient than CSS selectors.

await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible()

After clicking, the test navigates to the installation page. This assertion checks that a heading with the text “Installation” becomes visible. Again, Playwright retries this automatically.

Understanding the playwright.config.js File

The playwright.config.js file controls how your entire test suite runs. The default configuration sets up three test projects — one for each browser engine.

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
});

Key settings to know right now:

We will explore every option in detail in Part 5.

Running Your Tests

# Run the full suite across all browsers
npx playwright test

# Run only in one browser
npx playwright test --project=chromium

# Run a specific file
npx playwright test tests/example.spec.js

# Watch the browser open (headed mode)
npx playwright test --headed

# Open the interactive HTML report after a run
npx playwright show-report

# Open UI Mode — live debugging with a built-in browser and test explorer
npx playwright test --ui

When tests pass, you will see:

Running 6 tests using 3 workers
  6 passed (8.3s)

That “6 tests” comes from 2 test cases × 3 browser projects.

Reading a Failure

Break one of the assertions intentionally:

await expect(page).toHaveTitle(/NotARealTitle/);

Run again. Playwright will print:

Error: expect(page).toHaveTitle(expected)

Expected pattern: /NotARealTitle/
Received string:  "Fast and reliable end-to-end testing for modern web apps | Playwright"

The diff is clear and actionable. The HTML report adds a screenshot of the page at the moment of failure, and if tracing is enabled, a full step-by-step replay.

Summary

Here is what you learned in Part 1:

• Playwright is an E2E testing framework that drives real browsers
• It supports Chromium, Firefox, and WebKit with auto-waiting built in
• npm init playwright@latest scaffolds a working project in seconds
• A test is an async function that receives a page fixture
• expect() assertions are web-first: they retry until they pass or time out
• playwright.config.js controls browsers, parallelism, retries, and more
• npx playwright test runs everything; --project and --headed are useful flags

What’s Next

In Part 2, we dive deep into locators — the API you will use in every single test to find elements on the page. You will learn why getByRole is almost always the right choice, and when to reach for other strategies.

The post What Is Playwright and Why Should You Care? appeared first on Swacblooms🦋.

After implementing track toggling with replaceTrack(), a crucial question emerges: When do I need to renegotiate (create a new offer/answer) vs when can I just swap tracks?

Understanding this is critical for building efficient WebRTC applications. Unnecessary renegotiation adds latency and complexity, while missing required renegotiation breaks your connection.

Quick Answer

Use replaceTrack() (no renegotiation) when:

• Swapping tracks of the same type (camera 1 → camera 2)
• Toggling tracks on/off (video → null → video)
• The transceiver slot already exists

Renegotiate (new offer/answer) when:

• Adding new transceivers (new media types)
• Changing transceiver direction
• Stopping transceivers permanently
• Any structural SDP changes

What is a Transceiver?

A transceiver is a bidirectional media slot in your peer connection:

// Creates a slot for video communication
const transceiver = peerConnection.addTransceiver('video', {
  direction: 'sendrecv'  // Can send AND receive
})

// The transceiver has:
// - sender: sends your video to the peer
// - receiver: receives peer's video
// - direction: sendrecv, sendonly, recvonly, inactive

Key insight: Once a transceiver exists, you can swap tracks in/out without renegotiation. The slot is reserved for the connection lifetime.

The SDP Connection

Renegotiation is required when the SDP (Session Description Protocol) structure changes:

v=0
o=- 123456 2 IN IP4 127.0.0.1
s=-
t=0 0
m=video 9 UDP/TLS/RTP/SAVPF 96 97    ← Video m-line (transceiver slot)
m=audio 9 UDP/TLS/RTP/SAVPF 111      ← Audio m-line (transceiver slot)

• Each m= line represents a transceiver
• Adding/removing m-lines = renegotiation required
• Changing direction in m-line = renegotiation required
• Swapping tracks within existing m-line = NO renegotiation needed

Scenarios: No Renegotiation Needed

1. Camera Toggling (On → Off → On)

let videoSender: RTCRtpSender | null = null

// Initial setup: create transceiver
const videoTransceiver = peerA.addTransceiver(videoTrack, {
  direction: 'sendrecv',
  streams: [localStream]
})
videoSender = videoTransceiver.sender

// Later: Turn camera OFF
await videoSender.replaceTrack(null)  //  NO renegotiation

// Later: Turn camera ON
const newStream = await getUserMedia({ video: true })
const newTrack = newStream.getVideoTracks()[0]
await videoSender.replaceTrack(newTrack)  //  NO renegotiation

Why it works: The video transceiver slot exists. We’re just changing what goes into it (track → null → track).

2. Switching Cameras

// Front camera → Back camera
const constraints = { video: { facingMode: 'environment' } }
const newStream = await getUserMedia(constraints)
const newTrack = newStream.getVideoTracks()[0]

await videoSender.replaceTrack(newTrack)  //  NO renegotiation

Why it works: Same transceiver, different video source.

3. Switching Microphones

// Default mic → Headset mic
const constraints = { audio: { deviceId: headsetMicId } }
const newStream = await getUserMedia(constraints)
const newTrack = newStream.getAudioTracks()[0]

await audioSender.replaceTrack(newTrack)  //  NO renegotiation

Why it works: Same transceiver, different audio source.

4. Changing Video Resolution/Frame Rate

// 720p → 1080p
const constraints = {
  video: { width: 1920, height: 1080, frameRate: 30 }
}
const newStream = await getUserMedia(constraints)
const newTrack = newStream.getVideoTracks()[0]

await videoSender.replaceTrack(newTrack)  //  NO renegotiation

Why it works: Still using the same video transceiver.

Scenarios: Renegotiation Required

1. Adding Screen Sharing

// Initial: video + audio
const videoTransceiver = peerA.addTransceiver(videoTrack, {
  direction: 'sendrecv',
  streams: [localStream]
})
const audioTransceiver = peerA.addTransceiver(audioTrack, {
  direction: 'sendrecv',
  streams: [localStream]
})

// Create offer/answer...

// Later: Add screen sharing (NEW transceiver)
const screenStream = await navigator.mediaDevices.getDisplayMedia({
  video: true
})
const screenTrack = screenStream.getVideoTracks()[0]

// Adding a new transceiver
const screenTransceiver = peerA.addTransceiver(screenTrack, {
  direction: 'sendrecv',
  streams: [screenStream]
})

//  MUST renegotiate!
const offer = await peerA.createOffer()
await peerA.setLocalDescription(offer)

// Send offer to peer B
// Wait for answer from peer B
const answer = await receiveAnswerFromPeerB()
await peerA.setRemoteDescription(answer)

Why renegotiation is needed: We added a new m-line to the SDP. Peer B needs to know about this new media stream.

2. Changing Transceiver Direction

// Initial: bidirectional
const transceiver = peerA.addTransceiver('video', {
  direction: 'sendrecv'  // Can send AND receive
})

// Later: Make it send-only
transceiver.direction = 'sendonly'

// MUST renegotiate!
const offer = await peerA.createOffer()
await peerA.setLocalDescription(offer)
// ... complete negotiation

Why renegotiation is needed: The SDP m-line direction attribute changed. Peer B needs to update its expectations.

3. Stopping a Transceiver

const transceiver = peerA.getTransceivers()[0]

transceiver.stop()  // Permanently stops the transceiver

//  MUST renegotiate!
const offer = await peerA.createOffer()
await peerA.setLocalDescription(offer)
// ... complete negotiation

Why renegotiation is needed: The m-line is marked as inactive in SDP. This is a structural change.

Note: You rarely need to stop transceivers. Usually replaceTrack(null) is sufficient.

4. Adding Data Channels After Connection

// Initial connection with video/audio

// Later: Add data channel
const dataChannel = peerA.createDataChannel('fileTransfer')

//  MUST renegotiate!
const offer = await peerA.createOffer()
await peerA.setLocalDescription(offer)
// ... complete negotiation

Why renegotiation is needed: Data channels add application m-lines to SDP.

Performance Implications

replaceTrack() (No Renegotiation)

Performance:

• Near-instant (typically < 50ms)
• No network round-trip
• No SDP parsing
• Seamless for users

Use for:

• Real-time track toggling
• Device switching
• Quality changes

// Fast and seamless
console.time('replaceTrack')
await videoSender.replaceTrack(newTrack)
console.timeEnd('replaceTrack')  // ~10-30ms

Renegotiation (Offer/Answer)

Performance:

• Slow (typically 500ms – 2000ms)
• Multiple network round-trip
• SDP parsing on both sides
• Potential for brief disruption

Steps involved:

1. Create offer (100-200ms)
2. Set local description (50-100ms)
3. Send offer to peer (network latency)
4. Peer processes offer (50-100ms)
5. Peer creates answer (100-200ms)
6. Peer sets local description (50-100ms)
7. Answer sent back (network latency)
8. Set remote description (50-100ms)

// Slower due to network round trips
console.time('renegotiate')
const offer = await peerA.createOffer()
await peerA.setLocalDescription(offer)
await sendOfferToPeer(offer)
const answer = await waitForAnswer()
await peerA.setRemoteDescription(answer)
console.timeEnd('renegotiate')  // ~500-2000ms

Decision Tree

Do you need to add a NEW type of media?
├─ YES → Renegotiate (add transceiver, then offer/answer)
└─ NO
   │
   Do you need to change transceiver direction?
   ├─ YES → Renegotiate (change direction, then offer/answer)
   └─ NO
      │
      Do you need to permanently stop a transceiver?
      ├─ YES → Renegotiate (stop transceiver, then offer/answer)
      └─ NO
         │
         Just changing/toggling existing track?
         └─ YES → Use replaceTrack() 

Summary

The Golden Rule: If the transceiver slot exists, use replaceTrack(). If you need a new slot (or to modify slot properties), renegotiate.

The post WebRTC Renegotiation: When You Need It and When You Don’t appeared first on Swacblooms🦋.

Here’s how I configured it.

Garage Bucket-to-Website

Garage doesn’t currently support anonymous S3 access, so I used the bucket-to-website feature for public file access. This works by:

1. Setting the bucket name to match my public domain (e.g., cdn.myapp.com)

2. Enabling website mode via the Garage web UI

3. Pointing my DNS to Garage’s web endpoint

4. Uploading files via S3 API

5. Accessing files directly via public HTTP URLs on my domain

This provides persistent public access without pre-signed URLs – perfect for truly public assets like logos.

Environment Variables

Before (Cloudflare R2):

CLOUDFLARE_R2_ENDPOINT

CLOUDFLARE_R2_ACCESS_KEY_ID

CLOUDFLARE_R2_SECRET_ACCESS_KEY

CLOUDFLARE_R2_BUCKET_NAME

After (Garage):

GARAGE_S3_ENDPOINT=https://cdn.myapp.com # Public web endpoint (matches bucket name)

GARAGE_S3_API_ENDPOINT=https://s3-api.myapp.com # S3 API endpoint (optional)

GARAGE_S3_ACCESS_KEY_ID=your_key_id

GARAGE_S3_SECRET_ACCESS_KEY=your_secret

GARAGE_S3_BUCKET_NAME=cdn.myapp.com # Must match public domain for website mode

Important: The bucket name must match your public domain for bucket-to-website to work.

S3 Client Configuration

The critical configuration for Garage compatibility:

var config = new AmazonS3Config

{

   ServiceURL = apiServiceUrl, // Garage S3 API endpoint

   ForcePathStyle = true, // Required for Garage

   AuthenticationRegion = "garage"

};

var s3Client = new AmazonS3Client(accessKeyId, secretAccessKey, config);

Key points:

– ForcePathStyle = true is required for Garage

– AuthenticationRegion = “garage” This is particularly important for non-AWS S3-compatible services like Garage that use custom region naming

– Separate API endpoint for uploads vs. public website endpoint for downloads

Upload Implementation

public async Task<string> UploadImageAsync(Stream fileStream, string fileName)

{

   var uniqueFileName = $"logos/{Guid.NewGuid()}{Path.GetExtension(fileName)}";

   var putRequest = new PutObjectRequest

   {

      BucketName = _bucketName,

      Key = uniqueFileName,

      InputStream = fileStream,

      ContentType = contentType,

      UseChunkEncoding = false // Important for compatibility

   };

   await _s3Client.PutObjectAsync(putRequest);

   // Return public website URL

   return $"{_publicEndpoint}/{uniqueFileName}";

}

The returned URL (https://cdn.myapp.com/logos/abc123.png) is directly accessible – no auth needed.

Migrating Existing Assets

I used a simple script to transfer existing files from R2 to Garage. The script downloaded files from R2 and re-uploaded them to Garage using the S3 API, preserving the same file paths for zero downtime.

Key Takeaways

Critical configuration:

– ForcePathStyle = true and AuthenticationRegion = “garage” are essential

– UseChunkEncoding = false prevents upload issues

– Bucket name must match your public domain for website mode

– DNS must point to Garage’s web endpoint

Why bucket-to-website:

– Garage doesn’t support anonymous S3 access yet

– Provides persistent public access without pre-signed URLs

– Perfect for truly public assets (logos, images, etc.)

Why Garage:

– Fixed costs instead of variable API/bandwidth charges

– Full control over storage infrastructure

– S3 is compatible with minimal code changes

For side projects where cost predictability matters, Garage is excellent. Self-hosting means I know exactly what I’m paying each month.

—

Resources:

– Garage Documentation

– AWSSDK.S3 NuGet Package

The post Migrating from Cloudflare R2 to Garage in .NET appeared first on Swacblooms🦋.

MCP stands for Model Context Protocol. It is a standard that outlines how large language models can interact with tools, commands or function execution to provide more context to them.

How MCP Works in VSCode

Visual Studio Code serves as the host and manages launching the MCP clients.

The MCP client interacts with LLMs and understands how to interact with MCP servers to invoke tools or add more context to its interaction with LLMS. In this case, the client is GitHub Copilot Agent.

The MCP server can be implemented either by hosting a literal web server or by using a standard input and output CLI tool(npm, docker etc) that can interact using the MCP standard

MCP protocol uses JSON-RPC to communicate. The JSON I’ll be posting below will be formatted, but the standard requires that the JSON is void of a new line (“\n”).

The protocol also requires that responses return the same ID from the request.

I tried implementing a partial MCP server that allows execution of MCP tools and doesn’t support features like sampling, batching, logging or sending errors.

What the tool does is that it returns a random quote based on the hour of the day. All communication between the server and client is through the standard input and output stream.

I used VSCode Insider, since the docs said this feature is still in preview. This is what the flow looks like.

• The Client (GitHub Copilot) sends an initialisation request that looks like this

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {}
    },
    "clientInfo": {
      "name": "Visual Studio Code - Insiders",
      "version": "1.101.0-insider"
    }
  }
}

• Then my MCP server replies with this

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "version": "1.0.0"
    },
    "instructions": "Helps returning quotes based on the time of the day."
  }
}

• Then the Client (GitHub Copilot Agent) sends a notification

{
  "method": "notifications/initialized",
  "jsonrpc": "2.0"
}

In my implementation, I didn’t handle this notification. Notifications in the MCP protocol are one-way messages.

• The client then makes a request to my server asking it to list the available tools and their required arguments.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

• Then my server returns a list of tools using the MCP spec. I attached attributes to the methods that I wanted to expose, and then I used reflection to dynamically generate the data.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_time_based_quotes",
        "description": "Get a quote based on the hour of day",
        "inputSchema": {
          "type": "object",
          "properties": {
            "hour": {
              "type": "integer",
              "description": "Parameter hour"
            }
          },
          "required": [
            "hour"
          ]
        }
      },
      {
        "name": "say_hello",
        "description": "Say hello to someone",
        "inputSchema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Parameter name"
            }
          },
          "required": [
            "name"
          ]
        }
      }
    ]
  }
}

• When I write a prompt that invokes my tool from GitHub Copilot chat, I get this message

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_time_based_quotes_based",
    "arguments": {
      "hour": 7
    },
    "_meta": {
      "progressToken": "bc9350cd-4d19-44ec-ac12-2056f11983a4"
    }
  }
}

• Then my MCP server returns this

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Every morning is a new beginning. Take a deep breath and start again."
      }
    ]
  }
}

The video below shows all this in VS Code.

From the video above, you can see that I am using the new dotnet run app.cs new feature that is still in preview

To learn more about MCP, check out its specifications. And to learn more about the dotnet run app.cs feature, check out their blog post.

My basic MCP server implementation can be seen here

Thanks for reading and bye

The post Implementing the MCP Stdio Transport Layer in .NET for VSCode Integration appeared first on Swacblooms🦋.

I tried bootstrapping an ASP.NET cohosted Orleans project using the Orleans and the PostgreSQL integration. When I tried to add a new migration, errors were thrown because the Orleans integration required some environment variables to be available. Those variables are only available and injected when running your project through the Aspire AppHost project.

The code below is a snippet of the initial state of the code that resorted to errors when I tried to run my entity framework migrations.

builder.Services.AddDbContextPool<AppDbContext>(options =>
{
    options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb")
        ,npgsqlOptionsAction: handleDbRetry()).UseExceptionProcessor();
});
builder.AddKeyedRedisClient("redis");
builder.UseOrleans(siloBuilder =>
{
      siloBuilder.Services.AddPooledDbContextFactory<AppDbContext>(options =>
      {
           options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb"),
               npgsqlOptionsAction: handleDbRetry());
      });
 });

When I execute dotnet ef migrations add [name of migration], the error snippet below is thrown

An error occurred while accessing the Microsoft.Extensions.Hosting services. Continuing without the application service provider. Error: Some services are not able to be constructed (Error while validating the service descriptor 'ServiceType: Orleans.Runtime.MembershipService.MembershipTableManager Lifetime: Singleton ImplementationType: Orleans.Runtime.MembershipService.MembershipTableManager':

To prevent this, I resorted to always commenting out the builder.UseOrleans block when I want to run migrations. And it worked but I couldn’t see myself always doing this moving forward. So I did some research and discovered that the migration command doesn’t inject any special environment variable when trying to add a migration.

I also discovered that you could add an environment variable which could be analysed before the builder.UseOrleans block runs. This works but I didn’t want to always add extra commands aside from executing the normal dotnet ef migration add command.

Finally, I found a way on Stackoverflow to detect if the dotnet ef migrations add command is executed .

All I needed to do was check if a particular letter combination was available in the executable file name or command line arguments tied to the dotnet ef migrations add process. The Environment.GetCommandLineArgs() method allows you to retrieve this and perform desired checks.

My final code block that does this seamlessly with the same dotnet ef migrations add command can be seen below.

var isMigrations = Environment.GetCommandLineArgs()[0].Contains("ef.dll");
builder.Services.AddDbContextPool<AppDbContext>(options =>
{
    options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb")
        ,npgsqlOptionsAction: handleDbRetry()).UseExceptionProcessor();
});
builder.AddKeyedRedisClient("redis");
if (!isMigrations)
{
    builder.UseOrleans(siloBuilder =>
    {
        siloBuilder.Services.AddPooledDbContextFactory<AppDbContext>(options =>
        {
            options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb"),
                npgsqlOptionsAction: handleDbRetry());
        });
    });
}

I just needed to check if the executable file name contained (“ef.dll”), if it did then that meant I was running a migration and there was no need to configure or set up the Orleans silo.

Thanks for reading. Bye

The post Running Entity Framework Migrations in an Aspire-Bootstrapped Orleans Project appeared first on Swacblooms🦋.

For someone pampered with the luxury of having a seamless debugging experience in Visual Studio IDE for C#, I also wanted to enjoy that comfort in a Laravel sail project setup. This led me to some exploration and luckily I found a light at the end of the tunnel.

Requirements

• Visual Studio Code
• PHP Debug Extension (here)
• PHP and Composer
• XDebug Browser Extension(here)

Browser Debugging

• I created a Laravel project setup called “mysail“

           composer create-project laravel/laravel mysail

• I navigated to the newly created project

          cd mysail

• I installed sail

           php artisan sail:install

• I added this environment variable to activate XDEBUG for debugging sessions

           SAIL_XDEBUG_MODE=develop,debug,coverage

• I started my sail environment

./vendor/bin/sail up

• I opened a new terminal and ran my migrations

./vendor/bin/sail artisan migrate

• I clicked on the “Run and Debug” option in VSCode
• I clicked on the “create a launch.json file“

• I clicked on the “PHP(XDebug)” option which opened some pre-configured debugging setup
• I looked for the one that had “Listen for Xdebug” and changed it from:

        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },

     to this


        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceRoot}"
            }
        },

The mapping enables the debugger to locate the right files to monitor set breakpoints.

• In my browser, I activated the XDebug browser extension by clicking on the “Debug” option of the extension

• I added a breakpoint to the home route to test if it works
• I clicked on the “Listen for Xdebug” button to activate the debugging session

• Now navigating to the website URL (localhost) stops exactly at line 6

• Yay!! it works, next I wanted to ensure I could use it to debug my test.
• I tried using the default scaffolded test created in a new Laravel project
• I added a breakpoint here:

• I opened a new terminal and ran this “./vendor/bin/sail debug test –filter test_the_application_returns_a_successful_response” instead of “./vendor/bin/sail artisan test –filter test_the_application_returns_a_successful_response”
• Note the difference in replacing “artisan” with “debug“
• And that worked as well

Things to note:

• Set your env: SAIL_XDEBUG_MODE=debug,debug,coverage before running “sail up“
• Add the path mapping to your PHP debugger VSCode configuration
• Activate the XDebug browser extension by clicking the “Debug” option when debugging browser requests.
• For your terminal debugging activities replace the “artisan” command with the word “debug”

Thanks for reading and bye

The post Using XDebug in Laravel Sail (VSCODE) appeared first on Swacblooms🦋.

Before I continue, I want to express my gratitude to the Orleans community for their support in addressing my queries. Special thanks to Ledjon Behluli and Reuben Bond for their invaluable contributions to the community.

Streams in Orleans enable your grains to react to a sequence of events. It allows the decoupling of the data generator from the data consumer.

Orleans’ extensibility allows developers to create custom stream providers to enable interoperability with the Orleans runtime.

Redis offers two popular messaging and real-time event-driven communication. They are:

• Redis Pub/Sub
• Redis Streams

I chose to write a Redis stream provider for Orleans due to the benefits Redis Stream has over Redis Pub/Sub. Redis stream supports message persistence, it also supports multiple consumers reading events at their own pace and other complex message processing.

For this article and project, I will be using Redis stream as a queue and a message broker.

To learn about streams in Orleans check these resources:

• Getting Started with Streams In Orleans
• Streams Implementation in Orleans

To learn about Redis Streams check here.

Building the Redis Streams Provider

Building a custom stream provider for Orleans requires implementing some interfaces.

The IQueueAdapterFactory interface is used for bootstrapping the components needed for a stream provider to be compatible with the Orleans runtime.

The IQueueAdapter interface enables the producer to send an event to the right queue and it also enables the Orleans runtime to know which queues to retrieve the events from before sending it to the consumer(Grain).

In Orleans each queue is assigned a pulling agent, the pulling agent retrieves a message from an assigned queue and sends it to a consumer which is a target Grain in Orleans.

You can decide to set the number of queues to one or more from your queue mapping settings when building the Orleans client and server host.

Orleans streams give you the freedom to use more than one queue to support various scalability, reliability and performance needs in a distributed system.

The IStreamFailureHandler interface enables you to define how you want to handle delivery errors to stream subscriptions.

The IQueueAdapterCache interface enables you to define how you want to handle the caching of the retrieved events from the queue.

The IStreamQueueMapper interface enables the stream/event producer to know which queue to push an event to by mapping the stream ID to a queue and it enables the runtime to know how many queues and cache to generate for the pulling agent.

Below is my implementation for the IQueueAdapterFactory interface:

public class RedisStreamFactory : IQueueAdapterFactory
{
    private readonly IDatabase _database;
    private readonly ILoggerFactory _loggerFactory;
    private readonly string _providerName;
    private readonly IStreamFailureHandler _streamFailureHandler;
    private readonly SimpleQueueCacheOptions _simpleQueueCacheOptions;
    private readonly HashRingBasedStreamQueueMapper _hashRingBasedStreamQueueMapper;

    public RedisStreamFactory(IDatabase database,
        ILoggerFactory loggerFactory,
        string providerName,
        IStreamFailureHandler streamFailureHandler,
        SimpleQueueCacheOptions simpleQueueCacheOptions,
        HashRingStreamQueueMapperOptions hashRingStreamQueueMapperOptions
        )
    {
        _database = database;
        _loggerFactory = loggerFactory;
        _providerName = providerName;
        _streamFailureHandler = streamFailureHandler;
        _simpleQueueCacheOptions = simpleQueueCacheOptions;
        _hashRingBasedStreamQueueMapper = new HashRingBasedStreamQueueMapper(hashRingStreamQueueMapperOptions, providerName);
    }

    public static IQueueAdapterFactory Create(IServiceProvider provider, string providerName)
    {
        var database = provider.GetRequiredService<IDatabase>();
        var loggerFactory = provider.GetRequiredService<ILoggerFactory>();
        var simpleQueueCacheOptions = provider.GetOptionsByName<SimpleQueueCacheOptions>(providerName);
        var hashRingStreamQueueMapperOptions = provider.GetOptionsByName<HashRingStreamQueueMapperOptions>(providerName);
        var streamFailureHandler = new RedisStreamFailureHandler(loggerFactory.CreateLogger<RedisStreamFailureHandler>());
        return new RedisStreamFactory(database, loggerFactory, providerName, streamFailureHandler, simpleQueueCacheOptions, hashRingStreamQueueMapperOptions);

    }

    public Task<IQueueAdapter> CreateAdapter()
    {
        return Task.FromResult<IQueueAdapter>(new RedisStreamAdapter(_database, _providerName, _hashRingBasedStreamQueueMapper, _loggerFactory));
    }

    public Task<IStreamFailureHandler> GetDeliveryFailureHandler(QueueId queueId)
    {
        return Task.FromResult(_streamFailureHandler);
    }

    public IQueueAdapterCache GetQueueAdapterCache()
    {
        return new SimpleQueueAdapterCache(_simpleQueueCacheOptions, _providerName, _loggerFactory);
    }

    public IStreamQueueMapper GetStreamQueueMapper()
    {
        return _hashRingBasedStreamQueueMapper;
    }
}

Next is my implementation of the IQueueAdapter interface, this interface enables the creation of a queue receiver. A receiver is generated for each queue. This interface is also used to send or push events to the queue. To push an event to the assigned queue, I had to use the inbuilt HashRingBasedStreamQueueMapper to obtain the queue a stream is assigned to. But you can write a custom queue mapper that suits your needs.

I also made use of the inbuilt SimpleQueueAdapterCache implementation to enable the caching of pulled events. But you can also use a custom one based on your needs.

In my implementation I made a batch of events to be a single event in Redis streams. I made the single event to comprise a stream’s namespace, a stream key, an event type and the actual data (event data).

This information will enable the queues pulling agent to know the consumer(Grain) for each event. Also do ensure that the Name property is properly set to the name of the stream provider.

The code below is my implementation of the interface.

public class RedisStreamAdapter : IQueueAdapter
{
    private readonly IDatabase _database;
    private readonly string _providerName;
    private readonly HashRingBasedStreamQueueMapper _hashRingBasedStreamQueueMapper;
    private readonly ILoggerFactory _loggerFactory;
    private readonly ILogger<RedisStreamAdapter> _logger;

    public RedisStreamAdapter(IDatabase database, string providerName, HashRingBasedStreamQueueMapper hashRingBasedStreamQueueMapper, ILoggerFactory loggerFactory)
    {
        _database = database;
        _providerName = providerName;
        _hashRingBasedStreamQueueMapper = hashRingBasedStreamQueueMapper;
        _loggerFactory = loggerFactory;
        _logger = loggerFactory.CreateLogger<RedisStreamAdapter>();
    }

    public string Name => _providerName;

    public bool IsRewindable => false;

    public StreamProviderDirection Direction => StreamProviderDirection.ReadWrite;

    public IQueueAdapterReceiver CreateReceiver(QueueId queueId)
    {
        return new RedisStreamReceiver(queueId, _database, _loggerFactory.CreateLogger<RedisStreamReceiver>());
    }

    public async Task QueueMessageBatchAsync<T>(StreamId streamId, IEnumerable<T> events, StreamSequenceToken token, Dictionary<string, object> requestContext)
    {
        try
        {
            foreach (var @event in events)
            {
                NameValueEntry streamNamespaceEntry = new("streamNamespace", streamId.Namespace);
                NameValueEntry streamKeyEntry = new("streamKey", streamId.Key);
                NameValueEntry eventTypeEntry = new("eventType", @event!.GetType().Name);
                NameValueEntry dataEntry = new("data", JsonSerializer.Serialize(@event));
                var queueId = _hashRingBasedStreamQueueMapper.GetQueueForStream(streamId);
                await _database.StreamAddAsync(queueId.ToString(), [streamNamespaceEntry, streamKeyEntry, eventTypeEntry, dataEntry]);
            }
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error adding event to stream {StreamId}", streamId);
        }
    }
}

Next, I implemented the IQueueAdapterReceiver interface, this implementation is used by pulling agents to retrieve messages or events from queues( Redis Stream) and sends the messages to the consumers (Grains). It also enables you to perform some cleanups or acknowledgement of processed messages using the MessagesDeliveredAsync method.

My implementation can be seen below.

public class RedisStreamReceiver : IQueueAdapterReceiver
{
    private readonly QueueId _queueId;
    private readonly IDatabase _database;
    private readonly ILogger<RedisStreamReceiver> _logger;
    private string _lastId = "0";
    private Task? pendingTasks;

    public RedisStreamReceiver(QueueId queueId, IDatabase database, ILogger<RedisStreamReceiver> logger)
    {
        _queueId = queueId;
        _database = database;
        _logger = logger;
    }

    public async Task<IList<IBatchContainer>?> GetQueueMessagesAsync(int maxCount)
    {
        try
        {
            var events = _database.StreamReadGroupAsync(_queueId.ToString(), "consumer", _queueId.ToString(), _lastId, maxCount);
            pendingTasks = events;
            _lastId = ">";
            var batches = (await events).Select(e => new RedisStreamBatchContainer(e)).ToList<IBatchContainer>();
            return batches;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error reading from stream {QueueId}", _queueId);
            return default;
        }
        finally
        {
            pendingTasks = null;
        }


    }

    public async Task Initialize(TimeSpan timeout)
    {
        try
        {
            using (var cts = new CancellationTokenSource(timeout))
            {
                var task = _database.StreamCreateConsumerGroupAsync(_queueId.ToString(), "consumer", "$", true);
                await task.WaitAsync(timeout, cts.Token);
            }
        }
        catch (Exception ex) when (ex.Message.Contains("name already exists")) { }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error initializing stream {QueueId}", _queueId);
        }
    }

    public async Task MessagesDeliveredAsync(IList<IBatchContainer> messages)
    {
        try
        {
            foreach (var message in messages)
            {
                var container = message as RedisStreamBatchContainer;
                if (container != null)
                {
                    var ack = _database.StreamAcknowledgeAsync(_queueId.ToString(), "consumer", container.StreamEntry.Id);
                    pendingTasks = ack;
                    await ack;
                }
            }
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error acknowledging messages in stream {QueueId}", _queueId);
        }
        finally
        {
            pendingTasks = null;
        }
    }

    public async Task Shutdown(TimeSpan timeout)
    {
        using (var cts = new CancellationTokenSource(timeout))
        {

            if (pendingTasks is not null)
            {
                await pendingTasks.WaitAsync(timeout, cts.Token);
            }
        }
        _logger.LogInformation("Shutting down stream {QueueId}", _queueId);
    }
}

Next, I created a new type called RedisStreamSequenceToken which I inherited from the StreamSequenceToken abstract class.

I needed a way to convert Redis streams event ID, into a form that is compatible with Orleans streams. so this inheritance did the magic. I converted the Redis stream ID timestamp section into the SequenceNumber property and the Redis stream sequence number section into the EventIndex property.

The inheritance requires using the GenerateSerializer attribute to mark the new type. This will enable the Orleans runtime to copy the object within its internals. You also need to ensure that the Microsoft.Orleans.Sdk is used to enable the proper generation of the serialized code.

The code below is my implementation:

public class RedisStreamSequenceToken : StreamSequenceToken
{
    [Id(0)]
    public override long SequenceNumber { get; protected set; }
    [Id(1)]
    public override int EventIndex { get; protected set; }

    public RedisStreamSequenceToken(RedisValue id)
    {

        var split = id.ToString().Split("-");
        SequenceNumber = long.Parse(split[0]);
        EventIndex = int.Parse(split[1]);
    }
    public RedisStreamSequenceToken(long sequenceNumber, int eventIndex)
    {
        SequenceNumber = sequenceNumber;
        EventIndex = eventIndex;
    }
    public override int CompareTo(StreamSequenceToken other)
    {
        if (other is null) throw new ArgumentNullException(nameof(other));
        if (other is RedisStreamSequenceToken token)
        {
            if (SequenceNumber == token.SequenceNumber)
            {
                return EventIndex.CompareTo(token.EventIndex);
            }
            return SequenceNumber.CompareTo(token.SequenceNumber);
        }
        throw new ArgumentException("Invalid token type", nameof(other));
    }

    public override bool Equals(StreamSequenceToken other)
    {
        var token = other as RedisStreamSequenceToken;
        return token != null && SequenceNumber == token.SequenceNumber && EventIndex == token.EventIndex;
    }
}

Finally, I implemented the IBatchContainer interface. This interface enables you to define a container for an event or a list of events. However, in my implementation, I made it to only encapsulate a single event or message from Redis streams.

Orleans streams support having heterogeneous types. This means that the queueing system can hold different types of data structures and Orleans will be able to deserialize it with your custom deserializer into the proper type required by the the event consumers.

It also has a generic method called GetEvents<T>(). This method enables the pulling agent to check if the batch container has the type of data required by the subscribed grain.

Below is my implementation:

public class RedisStreamBatchContainer : IBatchContainer
{
    public StreamId StreamId { get; }

    public StreamSequenceToken SequenceToken { get; }
    public StreamEntry StreamEntry { get; }
    public RedisStreamBatchContainer(StreamEntry streamEntry)
    {
        StreamEntry = streamEntry;
        var streamNamespace = StreamEntry.Values[0].Value;
        var steamKey = StreamEntry.Values[1].Value;
        StreamId = StreamId.Create(streamNamespace!, steamKey!);
        SequenceToken = new RedisStreamSequenceToken(StreamEntry.Id);
    }
    public IEnumerable<Tuple<T, StreamSequenceToken>> GetEvents<T>()
    {
        List<Tuple<T, StreamSequenceToken>> events = new();
        var eventType = typeof(T).Name;
        if (eventType == StreamEntry.Values[2].Value)
        {
            var data = StreamEntry.Values[3].Value;
            var @event = JsonSerializer.Deserialize<T>(data!);
            events.Add(new(@event!, SequenceToken));
        }
        return events;
    }

    public bool ImportRequestContext()
    {
        return false;
    }
}

One last thing you should note is that when setting up the Factory settings ensure the same configuration of queues is set on both the Orleans server and the client.

For instance, if I want 4 queues to be created then I have to set the number of queues in both the client and the server to be the same. The code below shows that:

// client
using IHost host = new HostBuilder()
     .UseOrleansClient(clientBuilder =>
     {
         clientBuilder.Services.AddSingleton<IDatabase>(sp =>
         {
             IDatabase db = ConnectionMultiplexer.Connect("localhost").GetDatabase();
             return db;
         });
         clientBuilder.UseLocalhostClustering();

         clientBuilder.AddPersistentStreams("RedisStream", RedisStreamFactory.Create, null);
         clientBuilder.ConfigureServices(services =>
         {
             services.AddOptions<HashRingStreamQueueMapperOptions>("RedisStream")
                 .Configure(options =>
                 {
                     options.TotalQueueCount = 4;
                 });

         });
     })
     .ConfigureLogging(logging => logging.AddConsole())
     .Build();

// server
var builder = new HostBuilder()
    .UseOrleans(silo =>
    {
        silo.UseLocalhostClustering();
        silo.Services.AddSingleton<IDatabase>(sp =>
        {
            return ConnectionMultiplexer.Connect("localhost").GetDatabase();
        });
        silo.ConfigureLogging(logging => logging.AddConsole());
        silo.AddMemoryGrainStorage("PubSubStore");
        silo.AddPersistentStreams("RedisStream", Provider.RedisStreamFactory.Create, null);
        silo.AddMemoryGrainStorageAsDefault();
    }).UseConsoleLifetime();
builder.ConfigureServices(services =>
{
    services.AddOptions<HashRingStreamQueueMapperOptions>("RedisStream")
        .Configure(options =>
        {
            options.TotalQueueCount = 4;
        });
    services.AddOptions<SimpleQueueCacheOptions>("RedisStream");
});
using IHost host = builder.Build();

Thanks for reading through, a working project that stitches everything together can be seen here.

The post Custom Redis Streams Provider for Orleans appeared first on Swacblooms🦋.

The purpose of this project is not to create a production ready storage provider but something I can use to easily visualize the data persistence during app development and also get a better understanding of persistence in Orleans .

The image below illustrates what the custom file persistence layer looks like

To create a custom storage provider, I had to implement the IGrainStorage interface which is structured below:

public interface IGrainStorage
{
  Task ReadStateAsync<T>(string stateName, GrainId grainId, IGrainState<T> grainState);
  Task WriteStateAsync<T>(string stateName, GrainId grainId, IGrainState<T> grainState);
  Task ClearStateAsync<T>(string stateName, GrainId grainId, IGrainState<T> grainState);
}

Looking at the interface you can see that they all have similar signature, bearing “stateName“, “grainId” and “grainState” as parameters.

A Grain can have multiple states stores so the “stateName” helps to identity the particular state during data persistence from a Grain.

A Grain’s Id comprises of two important things: The type and the key.

Let’s say I have a Grain called “VotingGrain”. By default the Grain’s type is identified as “voting“

The key is the unique value sent by the client to interact with the a particular Grain. In the code below the Grain’s key is idenitified as “football“.

var soccerPolls = client.GetGrain<IVotingGrain>("football");

And finally from the IGrainStorage interface, the IGrainState<T> parameter holds a reference to the data in a Grain.

To use the Options pattern while creating the File Storage provider extension, I created the the type below:

    public class FileConfigurationOptions
    {
        // the location of the folder to use as a store
        public string? StorePath { get; set; }

        // the section in the config file to retrieve store path from
        public const string MyFileConfiguration = "FileConfiguration";
    }

Next, I created the file storage provider by implementing the IGrainStorage interface

public class FileStorage : IGrainStorage
{
    private void _ensureFileExists(string filePath)
    {
        if (!File.Exists(filePath))
        {
            var directory = Path.GetDirectoryName(filePath);
            Directory.CreateDirectory(directory!);
            File.Create(filePath).Close();
        }
    }

    private string _getFilePath(GrainId grainId, string stateName)
    {
        return Path.Combine(_options.Value.StorePath!, grainId.Type.ToString()!, grainId.Key.ToString()!, stateName + ".json");
    }
    private readonly IOptions<FileConfigurationOptions> _options;
    public FileStorage(IOptions<FileConfigurationOptions> options) => _options = options;
    public Task ClearStateAsync<T>(string stateName, GrainId grainId, IGrainState<T> grainState)
    {
        var path = _getFilePath(grainId, stateName);
        File.Delete(path);
        return Task.CompletedTask;
    }

    public async Task ReadStateAsync<T>(string stateName, GrainId grainId, IGrainState<T> grainState)
    {
        var path = _getFilePath(grainId, stateName);
        _ensureFileExists(path);
        var data = await File.ReadAllTextAsync(path);
        if (string.IsNullOrEmpty(data)) return;
        grainState.State = JsonSerializer.Deserialize<T>(data)!;
    }

    public async Task WriteStateAsync<T>(string stateName, GrainId grainId, IGrainState<T> grainState)
    {
        var path = _getFilePath(grainId, stateName);
        _ensureFileExists(path);
        var data = JsonSerializer.Serialize(grainState.State);
        await File.WriteAllTextAsync(path, data);
    }
}

The storage implementation above uses a combination of Grain’s ID Type, Grain’s ID Key and Grain’s stateName to create the file path to the file that holds the stored data.

One limitation of the storage provider mentioned above is that I didn’t use ETags to prevent concurrency issues. If the AlwaysInterleave attribute setting is enabled for a Grain’s method that writes to storage, it could cause errors due to race conditions. However, without this configuration, everything works fine

Next, I created my extension method to easily help me setup the File Storage provider in Orleans. I created two methods, the first overload allows you to set the path of the “filestore” directly in the code while the second one reads the path from the Orleans configuration file.

    public static class FileStorageExtensions
    {
        public static IServiceCollection AddFileStorage(this IServiceCollection services, Action<FileConfigurationOptions> configureOptions)
        {
            services.AddOptions<FileConfigurationOptions>()
                       .Configure(configureOptions);
            return services.AddKeyedSingleton<IGrainStorage, FileStorage>("fileStateStore");
        }

        public static IServiceCollection AddFileStorage(this IServiceCollection services)
        {
            services.AddOptions<FileConfigurationOptions>()
               .Configure<IConfiguration>((settings, configuration) =>
               {
                   configuration.GetSection(FileConfigurationOptions.MyFileConfiguration).Bind(settings);
               });
            return services.AddKeyedSingleton<IGrainStorage, FileStorage>("fileStateStore");
        }
    }

You can see above that Orleans makes use of the AddKeyedSingleton feature to identify the store implementation.

And finally, I configured Orleans to use the custom file provider below:

IHostBuilder builder = new HostBuilder()
    .UseOrleans(silo =>
    {
        silo.UseLocalhostClustering();
        silo.Services.AddFileStorage();
    });

builder.ConfigureAppConfiguration((context, config) =>
{
    config.AddJsonFile("path_to_config_file.json", optional: true);
});
using IHost host = builder.Build();

await host.RunAsync();

Now when I select the store using the “fileStateStore” value in the PersistentState attribute of the Grain’s constructor, the Grain persists its data using the custom store which can be seen in the code below:

public class PersonGrain : IGrainBase, IPersonGrain
{
    IPersistentState<PersonState> state;
    public IGrainContext GrainContext { get; }
    public PersonGrain(IGrainContext context, [PersistentState("personState", "fileStateStore")] IPersistentState<PersonState> state) => (GrainContext, this.state) = (context, state);

    public async Task AddName(string name)
    {
        var context = this.GrainContext;
        state.State.Name = name;
        await state.WriteStateAsync();
    }
    public Task<string> GetName()
    {
        return Task.FromResult($"My name is {state.State.Name}");
    }
}


public class PersonState
{
    public string? Name { get; set; }
}

Thanks for reading through, the link to the project can be seen here.

To learn more about Grain persistence in Microsoft Orleans click here.

Bye

The post Creating a Custom File Storage Provider for Microsoft Orleans appeared first on Swacblooms🦋.