DEV Community: Ravi Kishan

How RelaxCSS Works: Building a TailwindCSS-Like Utility Engine

Ravi Kishan — Tue, 24 Jun 2025 05:59:38 +0000

Overview and Introduction

RelaxCSS is a lightweight, Tailwind-inspired utility-first CSS engine implemented as a PostCSS plugin and CLI tool. Like Tailwind, it provides a rich set of pre-defined utility classes (e.g. p-4, bg-blue-500, hover:text-white) and a configuration-driven design system. RelaxCSS aims to be minimal and extensible: it supports custom theme values (colors, spacing, etc.), responsive and pseudo-class variants, JIT compilation of only used utilities, and a plugin API for adding new utilities. Under the hood, a “preflight” (CSS reset) is injected (similar to Tailwind’s) and directives like @apply and @relax in CSS enable class composition.

In practice, you install RelaxCSS, write your CSS/HTML with utility classes, and run the CLI (or PostCSS plugin) to watch your files. The tool scans source files for class names (using glob patterns and regex), generates the corresponding utility CSS on-the-fly (JIT), and writes out a final output.css. The default configuration (which you can customize via relaxcss.config.js) includes sensible defaults for colors, spacing, screens, etc., and even a built-in example plugin (adding a fancy-border utility). Overall, RelaxCSS provides a Tailwind-like workflow—class-heavy markup and zero custom CSS—while remaining small and easy to extend.

Architecture Overview

RelaxCSS consists of several major components that work together in a build pipeline:

CLI/Watcher: A command-line interface (cli.ts/cli-watch.ts) runs RelaxCSS. It uses glob and chokidar to watch source files (HTML, CSS, JS, etc.) and trigger rebuilds on changes.
File Scanner (JIT Engine): The CLI watches file patterns (e.g. src/**/*.{html,js,jsx,ts,tsx,css}), reads each file’s content, and extracts class names with regex.
PostCSS Parser: RelaxCSS is implemented as a PostCSS plugin. The plugin receives the CSS AST parsed from your combined stylesheet (including your @apply rules).
Theme/Config: User configuration (from relaxcss.config.js or plugin options) is merged with the default theme/variants. This config object (colors, spacing, screens, etc.) is provided to the plugin and to any utility-generating code.
Utility Generator (Plugin Logic): The core plugin takes each utility class name (or @apply directive) and generates the corresponding CSS declarations based on the theme config. It supports responsive prefixes (e.g. md:), pseudo-classes (e.g. hover:), and even arbitrary values (bg-[#222]).
Output Generator: After PostCSS transforms (including preflight injection and @apply resolution), the plugin emits the final CSS. The CLI then writes this CSS to the output file (e.g. dist/output.css).

In this flow, the CLI initiates file scanning (with glob and chokidar) and combines CSS and @apply rules. The PostCSS parser parses the CSS, and the RelaxCSS plugin transforms it: injecting base styles (preflight), resolving @apply by inlining utility declarations, and wrapping rules in media/pseudo selectors. The theme/config drives which CSS values get used. Finally, the Output Generator writes out the CSS file.

Theme and Configuration System

RelaxCSS is highly configurable via a relaxcss.config.js (or via plugin options). The user config can define custom theme values (colors, spacing, fonts, etc.), responsive breakpoints, variants (e.g. which pseudo-classes to enable), plugins, and more. Internally, RelaxCSS starts with a defaultConfig (built-in) and merges the user’s config into it using lodash.merge:

const mergedConfig = merge(defaultConfig, opts);

This merged config object, mergedConfig, contains all theme scales. For example, the default theme includes a screens section (for breakpoints) and a spacing section:

theme: {
  screens: { sm: "640px", md: "768px", lg: "1024px", xl: "1280px" },
  spacing: { px: "1px", 0: "0px", 1: "0.25rem", 2: "0.5rem", … },
  colors: { transparent:"transparent", white:"#fff", blue: {50:"#eff6ff", 100:"#dbeafe", …}, … },
  fontSize: { base:["1rem",{lineHeight:"1.5rem"}], xl:["1.25rem",{lineHeight:"1.75rem"}], … },
  // etc.
}

Within the plugin code, CSS generation functions access these theme values. For example, when handling max-w-<key> utilities, the code does:

if (className.startsWith("max-w-")) {
  const value = get(config.theme.maxWidth, suffix);
  if (value !== undefined)
    declarations.push(new Declaration({ prop: "max-width", value }));
}

Similarly, for font sizes (text-xl), it retrieves a tuple from config.theme.fontSize:

const fontSizeTuple = get(config.theme.fontSize, suffix);
if (Array.isArray(fontSizeTuple)) {
  declarations.push(new Declaration({ prop: "font-size", value: fontSizeTuple[0] }));
  if (fontSizeTuple[1]?.lineHeight) {
    declarations.push(new Declaration({ prop: "line-height", value: fontSizeTuple[1].lineHeight }));
  }
}

In summary, RelaxCSS loads user settings (via opts or a relaxcss.config.js), merges them with defaults, and then all parts of the system read from this mergedConfig.theme. The variants section (e.g. which media queries and which pseudo-classes to support) also comes from the config and drives how the plugin wraps utility rules for sm: or hover: prefixes.

Utility Parser and Generator

At the heart of RelaxCSS is the utility parser, which takes a class name like p-4, bg-[#222], or md:hover:bg-blue-500 and translates it into one or more CSS declarations. This logic lives in the function generateUtilityCss(className, config) in index.ts. The class name is split into a prefix (e.g. p, bg, text, etc.) and a suffix (the part after the dash). A series of if/else and switch statements handle each utility:

Spacing utilities (p-4, mt-2, mx-auto, etc.): use helper functions that look up the numeric key in config.theme.spacing and emit corresponding padding or margin declarations. For example, m-4 becomes margin: 1rem if spacing[4] = "1rem".
Size limits (max-w-lg, max-h-full): look up in config.theme.maxWidth or maxHeight (from the merged config) and emit max-width or max-height. See above in .
Colors and fonts: for text-<color>-<shade> or bg-<color>-<shade>, a helper (getColor) checks the nested config.theme.colors. For text-xl, it instead looks in config.theme.fontSize as shown in .

Importantly, RelaxCSS also supports arbitrary values via a special parser function. A class like bg-[#222] or p-[4px] matches the regex /^([a-z-]+)-\[(.+)\]$/. This extracts a prefix and a raw value. The code parseArbitraryValue(className, config) (see below) directly maps certain prefixes to CSS properties:

function parseArbitraryValue(className: string, config: RelaxConfig): Declaration[] {
  // e.g. bg-[#222], p-[4px], text-[red], w-[100px], m-[1rem], etc.
  const arbitraryMatch = className.match(/^([a-z-]+)-\[(.+)\]$/i);
  if (!arbitraryMatch) return [];
  const prefix = arbitraryMatch[1];
  const value = arbitraryMatch[2];
  // Map prefix to CSS property
  switch (prefix) {
    case "bg":
      return [new Declaration({ prop: "background-color", value })];
    case "text":
      return [new Declaration({ prop: "color", value })];
    case "border":
      return [new Declaration({ prop: "border-color", value })];
    case "w":
      return [new Declaration({ prop: "width", value })];
    case "h":
      return [new Declaration({ prop: "height", value })];
    // ... handle px, py, m, etc. in a similar way ...
    default:
      // fallback: treat prefix as the property name
      return [new Declaration({ prop: prefix, value })];
  }
}

When the PostCSS plugin encounters a utility class, it first tries parseArbitraryValue. If that returns declarations, it uses them directly (for example, bg-[#222] yields background-color: #222). Otherwise, it falls back to the standard generateUtilityCss logic for named utilities.

Responsive and pseudo variants: Class names can be prefixed with media queries or pseudo-classes, like sm:, md:, hover:, focus:, etc. In RelaxCSS this is handled in the plugin as well. The CLI/JIT will detect a class like md:hover:bg-blue-500 and enqueue it. The plugin code splits on ":" to see that md is a responsive variant and hover is a pseudo-variant, and then wraps the generated declarations accordingly. For example, md:hover:bg-blue-500 results in a rule inside a @media (min-width: 768px) block, with selector .md\:hover\:bg-blue-500:hover { background-color: ... }. (The plugin has helper code to do this, but the key point is that our design allows stacking variants in class names.)

For standard utilities (without variants), the code essentially turns a class into a CSS rule of the form .<class> { <declarations> }. For example, text-xl would lead to:

.text-xl {
  font-size: 1.25rem; /* from theme */
  line-height: 1.75rem; /* from theme */
}

Likewise, .bg-blue-500 { background-color: #3b82f6; }. Arbitrary values work similarly: .bg-\[\#222\] { background-color: #222; }.

Plugin System

RelaxCSS provides a plugin API so users can register additional utilities. A plugin is simply a function receiving an API object, e.g.:

interface RelaxPlugin {
  (api: {
    addUtilities: (utils: Record<string, (config: RelaxConfig) => Declaration[]>) => void;
    config: RelaxConfig;
  }): void;
}

Within this function, a plugin typically calls api.addUtilities(...) with new utility definitions. For example, the default config includes a built-in plugin that adds a fancy-border utility:

plugins: [
  function ({ addUtilities, config }) {
    addUtilities({
      "fancy-border": () => [
        // This utility generates: border:2px dashed magenta;
        new Declaration({ prop: "border", value: "2px dashed magenta" }),
      ],
    });
  },
],

After loading the config, RelaxCSS iterates through any plugins array (if provided) and calls each plugin function. The addUtilities calls aggregate into a userUtilities map. Later, during CSS generation, these custom utilities are treated just like built-in ones: if a class matches "fancy-border", RelaxCSS will output the declarations given by that plugin function.

This plugin mechanism allows anyone to extend RelaxCSS with their own custom shortcut classes (e.g. new color utilities, or even complex components) without modifying the core engine.

JIT Compilation and File Scanning

The CLI tool (cli-watch.ts) implements a Just-In-Time (JIT) engine. Instead of generating all possible utility classes, it scans your source files on-the-fly for exactly the classes you use. Key points:

File watching: The CLI takes a glob pattern like src/**/*.html and uses glob.sync to find matching files. It then sets up a watcher with chokidar.watch(srcGlob) to re-run the scan whenever any matching file changes. This makes it incremental and efficient.
Class extraction: For each source file, the code reads its contents and uses a regex to find class names. For HTML/JSX/etc, it matches class="...", className="...", or Vue :class="...", etc. The regex used is:
```
const classRegex = /(?:class|className|:class)\s*=\s*["'`\{[]([^"'`\}\]]+)["'`\}]/g;
```
Then it splits the captured class string on whitespace. For example, in <div class="text-xl p-4 hover:bg-red-500">, it will extract ["text-xl","p-4","hover:bg-red-500"].

CSS files are also scanned for @apply directives: another regex /@apply\s+([^;]+);/g pulls out any classes listed in an @apply statement.
Building CSS to apply: After scanning all files, the CLI builds a temporary CSS string where each found class is “applied” via @apply. For example, if it found text-lg and mt-4, it generates:
```
.text-lg { @apply text-lg; }
.mt-4 { @apply mt-4; }
```
(It also handles variants by calling a helper generateTailwindVariantRule, but ultimately it creates @apply rules for each used class.) This combined CSS (plus any raw CSS content) is then fed into PostCSS with the RelaxCSS plugin.
Automatic rebuilds: Thanks to chokidar, any file change triggers the scan-and-build process again. This ensures the output CSS is always up-to-date with the classes in your source.

Key code excerpts from cli-watch.ts:

// Scan files for classes and @apply
const files = glob.sync(srcGlob);
console.log(`[RelaxCSS] Processing files matching: ${files}`);
files.forEach((file) => {
  const ext = path.extname(file).slice(1);
  const content = fs.readFileSync(file, "utf8");
  if (ext === "css") {
    combinedCss += content + "\n";
    extractApplyClasses(content).forEach(cls => foundClasses.add(cls));
  } else if (fileExtensions.includes(ext)) {
    extractClassNames(content).forEach(cls => {
      foundClasses.add(cls);
      classNameFoundClasses.add(cls);
    });
  }
});

The extractClassNames and extractApplyClasses functions use regexes to find classes:

// In cli-watch.ts:
function extractClassNames(content: string): string[] {
  // Match class="...", className="...", etc.
  const classRegex =
    /(?:class|className|:class)\s*=\s*["'`\{[]([^"'`\}\]]+)["'`\}]/g;
  let match;
  while ((match = classRegex.exec(content))) {
    matches.push(...match[1].split(/\s+/).filter(Boolean));
  }
  return matches.filter(cls => !cls.startsWith("...")); // ignore Spread syntax
}

After extracting, the watcher rebuild logic looks like:

// Watch for changes and rebuild
const watcher = chokidar.watch(srcGlob, { ignoreInitial: true });
watcher.on("all", (event, filePath) => {
  console.log(`[RelaxCSS] Detected ${event} in ${filePath}. Rebuilding...`);
  processFiles();
});

This JIT pipeline – scan source → extract classes → generate @apply CSS → run RelaxCSS plugin – ensures that only used utilities end up in the final CSS. We can diagram it as:

Preflight and CSS Output

By default, RelaxCSS injects a small preflight (base reset) at the top of the CSS. This is similar to Tailwind’s Preflight and is meant to normalize browser defaults. In the plugin code, you can see it defines sections like “box-sizing”, “margin-padding”, “list-style”, etc.:

const preflightSections: Record<string, string> = {
  "box-sizing": `*,*::before,*::after{box-sizing:border-box;}`,
  "margin-padding": `body,h1,h2,h3,h4,h5,h6,p,ul,ol,li,figure,figcaption,blockquote,dl,dd{margin:0;padding:0;}`,
  "list-style": `ul:not([class]),ol:not([class]){list-style:none;}`,
  "font-family": `body{font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen,Ubuntu,Cantarell,"Open Sans","Helvetica Neue",sans-serif;line-height:1.5;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;}`,
  "media": `img,picture,video,canvas,svg{display:block;max-width:100%;}`,
  "form": `button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0;}`,
  "table": `table{border-collapse:collapse;}th,td{padding:0;}`,
};

These CSS snippets (with comments like /* RelaxCSS Preflight: box-sizing */) are prepended to the output. The preflight section of the config allows enabling/disabling parts or adding overrides, but by default all sections are included. For example, the first injected rule is *,*::before,*::after{box-sizing:border-box;} (ensuring consistent box-sizing).

After the plugin runs (resolving all @apply rules into concrete declarations and wrapping variants), the final CSS is emitted. In cli-watch.ts, this is done with PostCSS:

postcss([ relaxcss() ])
  .process(finalCss, { from: undefined })
  .then((result) => {
    fs.mkdirSync(path.dirname(outFile), { recursive: true });
    fs.writeFileSync(outFile, result.css, "utf8");
    console.log(`[RelaxCSS] Rebuilt: ${outFile}`);
  })
  .catch((err) => console.error("[RelaxCSS] Build error:", err));

So the final output is a single CSS file that begins with the preflight rules, followed by your combined utilities. All @apply rules have been replaced by their actual CSS declarations. For instance, if you had:

@relax;
.container { @apply flex bg-[#222] md:hover:bg-[#333]; }

the output might look like:

/* RelaxCSS Preflight: box-sizing */
*,*::before,*::after{box-sizing:border-box;}
/* RelaxCSS Preflight: margin-padding */
body,h1,...,dd{margin:0;padding:0;}
/* ... other preflight rules ... */

/* Utility classes */
.container {
  display: flex;
  background-color: #222;
}
@media (min-width:768px) {
  .md\:hover\:bg-\[\#333\]:hover {
    background-color: #333;
  }
}

In the example above, .container got display:flex (from the flex utility) and background-color:#222 (from bg-[#222]). The md:hover:bg-[#333] utility generated a media query rule for screens >=768px with the selector .md:hover:bg-[#333]:hover.

Example Output and Live Usage

Suppose we have an input CSS file like src/input.css:

/* src/input.css */
@relax;

.container {
  @apply flex bg-[#222] md:hover:bg-[#333];
}

.my-box {
  @apply fancy-border;
}

.ravi {
  @apply text-2xl;
}

.kishan {
  @apply text-3xl;
}

Here we use @relax; to trigger the plugin, and we apply several utilities:

flex, bg-[#222], and md:hover:bg-[#333] on .container.
fancy-border on .my-box (this was a custom utility from the default plugin).
text-2xl and text-3xl on .ravi and .kishan.

Running RelaxCSS on this (npx ts-node src/cli-watch.ts "src/**/*.{css,html,js,jsx,ts,tsx}" --out dist/output.css) will produce a dist/output.css roughly like:

/* RelaxCSS Preflight: box-sizing */
*,*::before,*::after{box-sizing:border-box;}
/* RelaxCSS Preflight: margin-padding */
body,h1,h2,h3,h4,h5,h6,p,ul,ol,li,figure,figcaption,blockquote,dl,dd{margin:0;padding:0;}
/* ... other preflight rules ... */

.container {
  display: flex;
  background-color: #222;
}
@media (min-width:768px) {
  .md\:hover\:bg-\[\#333\]:hover {
    background-color: #333;
  }
}
.my-box {
  border: 2px dashed magenta;
}
.ravi {
  font-size: 1.5rem;
  line-height: 2rem;
}
.kishan {
  font-size: 1.875rem;
  line-height: 2.25rem;
}

For live usage, one might have an HTML file like:

<button class="m-4">
  <span class="hover:bg-blue-500 hover:text-white md:hover:bg-blue-700 bg-[#222]">
    Hover over me
  </span>
</button>

When RelaxCSS processes this (in JIT mode), it will generate the equivalent CSS so that the button responds to hover and changes background/text color as expected.

Conclusion

RelaxCSS is a compact, flexible framework for utility-first styling, suitable for frontend developers and framework authors who want Tailwind-like productivity with a smaller footprint. It leverages a PostCSS plugin to parse utility class names (p-4, text-blue-500, hover:bg-red-200, etc.) and emit the corresponding CSS using values from a theme configuration. The CLI/JIT engine watches your files and includes only the utilities you actually use, keeping the CSS minimal. The plugin system lets you define your own utilities or copy Tailwind’s plugin approach. By supporting arbitrary values (bg-[#222]), responsive prefixes (md:) and variants (hover:), plus a built-in preflight reset, RelaxCSS covers most needs of modern utility-based development.

For advanced use, you can extend RelaxCSS by adding more functions to generateUtilityCss, writing plugins with addUtilities, or customizing the configuration. Because it’s just a PostCSS plugin and Node script, you could even integrate it into larger build tools or frameworks. Overall, RelaxCSS aims to be a learning-friendly, extensible alternative to Tailwind for projects where you want control over the utility engine’s internals. Users can build on this foundation – for example, adding support for more CSS features or improving performance – thanks to its clear architecture.

Sources: The above explanations and code snippets are drawn directly from the RelaxCSS source files (e.g. index.ts, cli-watch.ts, base.css).

Ravikisha / RelaxCSS

A next-generation, Tailwind-like JIT CSS/PostCSS plugin with a powerful plugin system, support for arbitrary values, variants (including dark mode and RTL), efficient watch mode, and CSS variable theme support. RelaxCSS can be used as a PostCSS plugin (recommended for most build pipelines) or as a standalone CLI tool.

RelaxCSS

A next-generation, Tailwind-like JIT CSS/PostCSS plugin with a powerful plugin system, support for arbitrary values, variants (including dark mode and RTL), efficient watch mode, and CSS variable theme support.

RelaxCSS can be used as a PostCSS plugin (recommended for most build pipelines) or as a standalone CLI tool.

PostCSS Plugin Usage

RelaxCSS is a drop-in PostCSS plugin. It works with PostCSS v8+ and integrates with any PostCSS-based build system (Webpack, Vite, Parcel, etc).

// postcss.config.js
const relaxcss = require('relaxcss');

module.exports = {
  plugins: [
    require('postcss-import'), // must be first
    relaxcss({
      // custom config here
    }),
    require('autoprefixer'),
    // ...
  ]
};

Supports all RelaxCSS features: JIT utilities, plugins, variants, dark mode, RTL, CSS variables, and more.
Use your relaxcss.config.js for custom configuration.
Compatible with PostCSS v8+ and all major build…

View on GitHub

npmjs.com

Building a Container Runtime from Scratch with Go (MyDocker)

Ravi Kishan — Thu, 05 Jun 2025 13:25:34 +0000

Table of Contents

Introduction: What is a Container Runtime?
Namespaces: Isolating Processes on Linux
Control Groups (cgroups): Managing Resources
Project Architecture: The MyDocker Design
- Command-Line Interface and Main.go
- Container Lifecycle (startContainer, child)
- Networking Isolation (Bridge and veth)
- Image Handling and OCI Unpacking
- Volumes and Port Mappings
Diagrams: Visualizing the Runtime
Getting Started and Resources

Introduction

Containers are lightweight, isolated environments for running applications. Unlike virtual machines, containers share the host kernel but isolate processes using kernel features like namespaces and cgroups. In this tutorial we’ll explore MyDocker, a simple container runtime written in Go, and walk through the key pieces that make it work. We’ll explain how MyDocker uses Linux namespaces (UTS, PID, network, mount, etc.) to isolate the container’s view of the system, and how it uses cgroups to limit resources. Along the way we’ll show key code snippets (e.g. startContainer, child, execContainer) and outline MyDocker’s architecture for CLI commands, networking, and image handling. By the end, you’ll see how MyDocker’s internals fit together, and how OCI image unpacking with tools like umoci and simple mount/iptables tricks provide the functionality of docker pull, run, exec, and more. We encourage you to check out the [MyDocker GitHub repository][22] and its [README][26] for examples and to try extending the code yourself.

Namespaces

Linux namespaces provide isolation by giving a process its own “view” of system resources. For example, PID namespaces mean a process can see only processes in its own container; UTS namespaces let each container have its own hostname; mount namespaces give each container its own filesystem root; network namespaces provide separate network interfaces/iptables, and so on. In other words, namespaces prevent processes in one container from seeing or affecting those in another. This isolation is a cornerstone of container security: “namespaces are quite flexible…they can be applied individually or in groups to one or more processes”. MyDocker’s container “child” process is created with clone flags for multiple namespaces (UTS, PID, NET, mount, etc.), so it runs in isolation. The code roughly follows the pattern:

// In main or run command:
cmd := exec.Command("/proc/self/exe", append([]string{"child"}, os.Args[2:]...)...)
cmd.SysProcAttr = &syscall.SysProcAttr{
    Cloneflags: syscall.CLONE_NEWUTS |
                syscall.CLONE_NEWPID |
                syscall.CLONE_NEWNET |
                syscall.CLONE_NEWNS, // etc.
}
cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
must(cmd.Run())

// The child() function runs inside the new namespaces:
func child() {
    // e.g., set hostname inside UTS namespace
    syscall.Sethostname([]byte("mydocker"))
    // Possibly mount proc, chroot, pivot_root, etc.
    // Finally exec the requested command:
    cmd := exec.Command(os.Args[2], os.Args[3:]...)
    cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
    must(cmd.Run())
}

As in other “container-from-scratch” examples, this pattern uses exec.Command("/proc/self/exe", "child", …) to re-invoke the same program in a new process (in new namespaces). From outside, the run command spawns the namespaced child; inside the container, the child function does setup (hostname, filesystem mounts, etc.) and then executes the user’s command. This effectively gives the container its own isolated environment separate from the host.

Figure: Container runtime architecture. MyDocker creates a namespaced “child” process for each container, mounts a fresh root filesystem (unpacked from an OCI image), applies cgroup limits, and sets up networking (bridge mydocker0 and veth pair). The CLI (main.go) drives commands like run, exec, pull, etc.

In summary, namespaces ensure that processes in MyDocker containers see only their own CPU, memory, filesystems, networks, and process list. This is one of the fundamental layers of container isolation. (MyDocker’s README also highlights this as a core feature: “Container process isolation using Linux namespaces (UTS, PID, NET, MNT)”.)

Control Groups (cgroups)

While namespaces isolate what a process sees, cgroups control how much of a resource a process can use. A control group (cgroup) is a Linux kernel feature that limits, accounts for, and isolates resource usage (CPU, memory, I/O, etc.) of a group of processes. MyDocker uses cgroups so that each container process has its own CPU and memory limits (as defined by CLI flags). For example, it might create a new cgroup under /sys/fs/cgroup/cpu/mydocker/<id> and write the PID of the container process into it, along with any limits (like cpu.shares or memory.limit_in_bytes). This means the container will only get a fraction of CPU or a fixed amount of memory, protecting the host and other containers.

“Cgroups are a kernel feature that allows you to partition and limit the system resources… that a group of processes can use. Think of them as virtual cages where you can corral your processes and set rules for their behavior”. (This quote describes cgroups in general; MyDocker uses them specifically for CPU and memory limits.)

For instance, MyDocker might contain code like:

// Simplified: create a cpu cgroup for the container
cgroupPath := filepath.Join("/sys/fs/cgroup/cpu/mydocker", containerID)
os.MkdirAll(cgroupPath, 0755)
// write the container's PID into the cgroup.procs file
os.WriteFile(filepath.Join(cgroupPath, "cgroup.procs"), []byte(pidStr), 0644)
// optionally set limits like cpu.shares or memory.limit_in_bytes

This ensures each container is “in its own cage”. The MyDocker README emphasizes resource control: “Resource control via cgroups (CPU & Memory)”. By combining cgroups with namespaces, the runtime isolates both the view and resources of each container process, similarly to how Docker does it behind the scenes.

Project Architecture

MyDocker’s source is structured simply (see [Architecture Overview][100]). At the top level we have:

main.go – The CLI entry point: parses commands like run, exec, pull, etc. It calls functions like startContainer() or execContainer() accordingly.
cgroups/ – Go package to set up cgroup directories and limits.
network/ – Go package to create a bridge (mydocker0) and virtual ethernet (veth) pairs for container networking.
helper.c – A small C program that is used to join existing namespaces (see below).
Other files: e.g. configuration templates, documentation.

The architecture overview in the README summarizes this:

“Architecture Overview: main.go — The CLI and container runtime entry point; cgroups/ — resource limits; network/ — bridge networks/veth; /var/lib/mydocker/ — stores metadata/images”.

So when you run something like sudo ./mydocker run -v /data:/data -p 8080:80 ubuntu:22.04 sh, what happens? A brief walkthrough:

CLI (main.go): The program parses the run command and container options (image name, mounts, ports, etc.). It likely calls a function startContainer(containerID, command, flags...).
startContainer: This function creates a unique container ID, sets up storage (image unpack, rootfs), sets up networking, then spawns a child process in new namespaces (using exec.Command("/proc/self/exe", ...) as above). It also records container metadata (like PID, rootfs path) under /var/lib/mydocker/.
Child process: In the new namespaces, it does further initialization: e.g., performs chroot/pivot_root into the unpacked image root filesystem; mounts the host directory if -v was given; configures networking (calls net.SetupVeth() to move one end of a veth into this namespace); then finally execs the user’s command (e.g. sh).
Networking: The network/ code ensures there is a Linux bridge (e.g. mydocker0) on the host. It creates a veth pair, moves one end into the child’s net namespace (as eth0), and attaches the other end to the mydocker0 bridge, giving the container network access (with its own IP).
Cgroups: Concurrently, before or after spawning the child, MyDocker creates new cgroup entries under CPU/memory controllers and adds the child’s PID, enforcing resource limits on that container.
Image Unpacking: For pulling images, MyDocker uses umoci. The pull command downloads an OCI image (like Ubuntu) and uses umoci unpack to extract it into a directory under /var/lib/mydocker. Umoci documentation explains: “umoci unpack - Unpacks an OCI image tag into a runtime bundle”. In other words, MyDocker relies on umoci to convert a container image into a rootfs directory with config, just like Docker does with layered filesystems.

Command-Line Interface and Main.go

The main.go file defines the CLI commands (run, exec, ps, etc.) using a library like urfave/cli. For example, when the user runs mydocker run ..., it ends up invoking something like:

func runCommandAction(ctx *cli.Context) error {
    imageName := ctx.Args().Get(0)
    cmd := ctx.Args().Get(1)
    flags := ctx.GlobalFlags()
    containerID := generateID()
    startContainer(containerID, imageName, cmd, flags)
    return nil
}

The core functions include startContainer (for run) and ExecContainer (for exec). In MyDocker, startContainer will unpack the image if needed, set up cgroups/networks, then clone a new process.

The execContainer function (called by mydocker exec) is also interesting. It finds the PID of an existing container process (by reading stored metadata) and then uses exec.Command("/proc/self/exe", "exec") to fork a helper process that enters that container’s namespaces (via a small C helper). Part of the code might look like:

func ExecContainer(containerID string, comArray []string) {
    pid, err := getPidByContainerId(containerID)
    // Set environment variables for the helper C program:
    cmd := exec.Command("/proc/self/exe", "exec")
    os.Setenv("mydocker_pid", pid)
    os.Setenv("mydocker_cmd", strings.Join(comArray, " "))
    cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
    cmd.Run()
}

This tells the re-invoked process to run the "exec" branch of main(). The helper C code (in helper.c) sees mydocker_pid/mydocker_cmd and performs setns() calls to join the PID/UTS/NET namespaces of that container, then uses system(mydocker_cmd) to run the desired command inside the container. (In effect, mydocker exec adds your shell to the existing container’s namespaces, letting you run commands inside it.) The Chinese blog [89] illustrates this pattern clearly. The key idea is: we fork a new process that points itself into the container’s namespaces and execs the command as if we were inside the container.

Container Lifecycle (`startContainer`, `child`)

Putting it all together, MyDocker’s container lifecycle roughly is:

Start: User runs mydocker run .... The Go main.go calls startContainer(...).
Setup: In startContainer, MyDocker creates a directory for the container under /var/lib/mydocker/<id>. It unpacks the OCI image rootfs there (if not done already), creates cgroups, sets up network (bridge/veth), and prepares the command arguments.

Clone (run): The code then does something like:

cmd := exec.Command("/proc/self/exe", append([]string{"child"}, commandArgs...)...)
cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
cmd.SysProcAttr = &syscall.SysProcAttr{
    Cloneflags: CLONE_NEWUTS | CLONE_NEWPID | CLONE_NEWNET | CLONE_NEWNS,
    UidMappings: ...,
    GidMappings: ...,
}
cmd.Run() // blocks until container process exits

This effectively forks into a child process that will run mydocker child ....

Child setup: In the child() function inside Go, the process is now in fresh namespaces. It performs actions similar to Docker’s container init:

- Calls `syscall.Chroot()` or `pivot_root()` to switch the root filesystem to the unpacked image.

- Applies mounts and volume binds (`syscall.Mount()`) for any `-v host:container` flags.

- Calls `net.SetupVeth()` to move one end of the veth into this namespace and bring up the network interface.

- Executes the container’s init process (e.g., `exec.Command("/bin/sh")`).

Run: The container process (PID 1 in its PID namespace) starts and runs user code. Meanwhile, the parent Go process (still the original CLI) waits (or returns immediately if detached).
Stop: When the container’s main process exits (e.g. you exit the shell), the child function returns. startContainer (the parent) will then do cleanup: remove cgroups, delete metadata, etc.

The code for startContainer and child in MyDocker is similar in spirit to many "from-scratch Docker" examples (e.g. [86]). For instance, the parent uses exec.Command("/proc/self/exe", "child", …) to create the child. Inside child, Go code uses syscalls (Mount, Chroot, Sethostname, etc.) to finish setting up the namespace, then exec.Command to run the actual command. Though we can’t cite the MyDocker source directly here, conceptually it follows the pattern above.

Networking

By default, containers should be able to talk to each other and the outside world (on certain ports). MyDocker’s network/ package likely does the following (in Go, via the vishvananda/netlink library or raw syscalls):

Ensure a Linux bridge exists (named mydocker0). If not, create it with ip link add name mydocker0 type bridge.
For each new container, create a veth pair (e.g. veth-host and veth-container). Move veth-container into the new namespace of the child (with netlink.LinkSetNsFd) and rename it to eth0.
Bring up eth0 inside the container and assign it an IP (e.g. via ip addr).
Attach veth-host to the mydocker0 bridge and bring it up on the host.

This way, containers get an IP on the mydocker0 network, and host-side NAT (iptables MASQUERADE) handles outbound traffic and port mapping. MyDocker’s README mentions a custom bridge network (mydocker0) and veth pairs for network isolation. (In our blog, we won’t go into all the iptables details, but that’s how host ports get forwarded: the CLI probably calls iptables -t nat rules so that -p host:container flags forward TCP from the host port to the container’s IP:port.)

Image Handling and OCI Unpacking

Container images (like ubuntu:22.04) come in the OCI/Docker image format. MyDocker supports pulling and unpacking these images using the umoci tool. The mydocker pull command likely shells out to umoci pull or similar, then umoci unpack. As the umoci manual states: “umoci unpack – Unpacks an OCI image tag into a runtime bundle”. In practice, MyDocker runs something like:

umoci unpack --image ubuntu:22.04 /var/lib/mydocker/images/ubuntu_22.04

This extracts the image layers and config into a directory that becomes the container’s root filesystem. MyDocker then stores this location (under /var/lib/mydocker/) so that future run commands can use the rootfs directly without repulling. The unpacked bundle includes /rootfs with all files and a JSON config. MyDocker’s Go code then chroot-es into that /rootfs when starting a container.

Using umoci (or a similar OCI utility) is important because it handles the layered filesystem format of images. Without overlay support, MyDocker unpacks into a single directory per image. The README cites “Simple OCI image unpacking using umoci” as a feature.

Volumes and Port Mappings

Volumes (-v): If the user specifies -v /host/dir:/container/dir, MyDocker will mount a bind mount inside the container namespace. The Go code in child() would do something like:

syscall.Mount("/host/dir", "/container/dir", "", syscall.MS_BIND, "")

after switching to the new root. This makes the host’s directory appear at the given path in the container. It relies on the mount namespace being isolated, so only the container sees the mount (the host’s filesystem is shared, but the namespace separates the mount list).

Port mappings (-p): For -p hostPort:containerPort, the runtime must forward network traffic. A simple approach: on the host, use iptables to NAT traffic from hostPort into the container’s IP and containerPort. For example:

iptables -t nat -A PREROUTING -p tcp --dport <hostPort> -j DNAT --to-destination <containerIP>:<containerPort>
iptables -t nat -A POSTROUTING -j MASQUERADE

This way, if a service inside the container listens on containerPort, requests to localhost:hostPort on the host will reach it. MyDocker’s implementation likely sets up such iptables rules automatically when starting the container, and removes them on stop. This achieves “port mapping” similar to Docker.

Diagrams

Below are some visual aids (using PlantUML) to illustrate the architecture and isolation concepts. These diagrams are simplified schematics.

These diagrams outline how the host CLI and services collaborate to create an isolated container process. In particular, the second diagram emphasizes that once the container process (C) is created, it has its own namespace instances and cannot see the host’s unrelated processes or network stacks.

Getting Started and Resources

MyDocker is intended as a learning tool to explore container internals. It “demonstrates how containerization works under the hood” and helps you understand namespaces, cgroups, and image formats. You can try it out by following the README instructions: for example, pull an image (mydocker pull ubuntu:22.04) and run it (mydocker run -it -v /data:/data -p 8080:80 ubuntu:22.04 bash) as shown in the usage examples. You’ll see your process isolated (check ps and hostname inside the container, and network connectivity to the bridge).

We encourage you to explore the Project Files (which includes source code and examples) and even extend it. Possible exercises include adding features like Dockerfile builds, overlayfs support, or enhanced networking. By tinkering with MyDocker’s code, you’ll gain a deep understanding of what happens in every docker run command. Happy hacking and containerizing!

Check out the github repo:

Ravikisha / MyDocker

MyDocker is a lightweight container runtime built from scratch in Go that demonstrates how containerization works under the hood — similar to Docker but in a simplified form.

🐳 MyDocker

MyDocker is a lightweight container runtime built from scratch in Go that demonstrates how containerization works under the hood — similar to Docker but in a simplified form.

👉 GitHub Repository

🚀 Features

Container process isolation using Linux namespaces (UTS, PID, NET, NS)
Resource control via cgroups (CPU & Memory)
Volume mounting (-v host:container)
Port mapping support (-p host:container)
Simple OCI image unpacking using umoci
Container image pulling, listing, and execution
Custom bridge network (mydocker0) and veth pairs for network isolation
Command-line interface similar to Docker (run, exec, ps, stop, pull, images, version)

🎯 Architecture

📦 Installation

Requirements

Go 1.19+

Root access (for namespace and networking)

umoci tool installed and in $PATH

Linux OS (recommended: Ubuntu)

git clone https://github.com/ravikisha/mydocker.git
cd mydocker
go build -o mydocker main.go
sudo ./mydocker version

…

View on GitHub

Introducing RelaxLang: A Beginner-Friendly Programming Language

Ravi Kishan — Thu, 16 Jan 2025 19:30:05 +0000

In the vast and ever-evolving world of programming languages, creating one from scratch is a feat that blends art, science, and a touch of magic. Today, I am excited to introduce RelaxLang, a simple yet powerful interpreted programming language. Inspired by Robert Nystrom's Crafting Interpreters and the Lox programming language, RelaxLang is designed to be accessible for beginners while being feature-rich for enthusiasts who want to dive deeper into language design and implementation.

Why RelaxLang?

RelaxLang stems from a vision to provide a lightweight, easy-to-understand programming language that serves as both a learning tool and a practical solution for basic scripting needs. Built with Java and C, it offers:

Dynamic Typing: Simplifies coding by inferring variable types at runtime.
First-Class Functions: Enables functional programming paradigms by treating functions as first-class citizens.
Classes and Inheritance: Introduces object-oriented programming with a straightforward syntax.
Built-In Standard Library: Provides out-of-the-box utilities for string manipulation, array operations, and more.

Whether you're an aspiring developer eager to learn how programming languages work or a seasoned programmer seeking an educational tool, RelaxLang caters to you.

Architecture

Key Features of RelaxLang

1. Dynamic Typing

In RelaxLang, you don’t need to worry about specifying types for variables. The interpreter takes care of it, allowing you to focus on logic and creativity.

var name = "RelaxLang";  // Automatically inferred as String
var version = 1.0;       // Automatically inferred as Float
var isActive = true;     // Automatically inferred as Boolean

print(name);            // Output: RelaxLang
print(version);         // Output: 1.0
print(isActive);        // Output: true

2. First-Class Functions

Functions are versatile in RelaxLang. They can be assigned to variables, passed as arguments, and even returned from other functions.

fun add(a, b) {
    return a + b;
}

var sum = add(5, 3);
print(sum);  // Output: 8

fun operate(func, x, y) {
    return func(x, y);
}

var result = operate(add, 10, 15);
print(result);  // Output: 25

3. Classes and Inheritance

RelaxLang supports object-oriented programming, making it a great tool to understand and implement OOP concepts.

class Animal {
    var name;

    init(name) {
        this.name = name;
    }

    fun speak() {
        print(this.name + " makes a sound.");
    }
}

class Dog < Animal {
    fun speak() {
        print(this.name + " barks.");
    }
}

var myDog = Dog("Buddy");
myDog.speak();  // Output: Buddy barks.

4. Control Flow

With intuitive if-else statements and loops, you can control the flow of your programs effortlessly.

var age = 18;

if (age < 18) {
    print("Minor");
} else {
    print("Adult");
}

for (var i = 0; i < 5; i = i + 1) {
    print(i);  // Output: 0 1 2 3 4
}

How to Get Started

1. Prerequisites

Ensure you have the following installed:

Java JDK 11 or later (Download here)
(Optional) Docker for a containerized setup

2. Installation

Clone the Repository:

git clone https://github.com/Ravikisha/RelaxLang.git
cd RelaxLang

Compile the Source Code:

javac src/*.java

3. Running RelaxLang

Using the JAR File:

java -jar lox.jar

Using Docker:

docker pull ravikishan63392/relaxlang:lastest
docker run -it ravikishan63392/relaxlang:lastest

Example Usage

RelaxLang scripts are simple to write and execute. For instance, here’s a script example.rl:

fun greet(name) {
    print("Hello, " + name + "!");
}

greet("World");

Run it with:

java -jar lox.jar example.rl

The Technical Journey

RelaxLang’s implementation involves:

Lexical Analysis: Breaking down source code into tokens.
Parsing: Constructing an Abstract Syntax Tree (AST) from tokens.
Interpreting: Executing the AST by traversing it node by node.

Developed in Java for platform independence and in C for low-level optimizations, RelaxLang’s design reflects a balance between simplicity and functionality.

Resources and Contributions

Docker Image:

RelaxLang Docker Image

GitHub Repository:

RelaxLang on GitHub

We welcome contributions! Whether it's bug fixes, feature requests, or documentation improvements, your input makes RelaxLang better. Please check out the contributing guidelines in the repository.

Final Thoughts

RelaxLang is not just a programming language; it’s a journey into the heart of language design. By exploring its features, experimenting with scripts, and diving into its implementation, you can gain insights into how modern programming languages work.

Give RelaxLang a try and embark on this exciting adventure. Let’s code, learn, and relax!

Building RelaxTube: A Scalable Video Transcoding and Streaming Application

Ravi Kishan — Tue, 14 Jan 2025 18:34:42 +0000

Introduction

RelaxTube is a feature-rich and scalable application designed to demonstrate the workflow of video transcoding and streaming. The project highlights the use of modern technologies like Node.js, React, Kafka, FFmpeg, MongoDB, and Docker. It efficiently processes videos by transcoding them into multiple quality levels, segmenting them for smoother streaming, and generating thumbnail previews.

This blog explores the architecture, key features, tech stack, installation, and potential enhancements for RelaxTube.

Key Features

Video Transcoding: Converts videos into multiple quality levels (360p, 480p, 720p, 1080p) using FFmpeg.
HLS Segmentation: Generates video segments for efficient HTTP Live Streaming (HLS) playback.
Thumbnail Generation: Automatically creates thumbnail previews for each uploaded video.
Batch Processing: Supports concurrent video processing using Kafka message queues.
Scalable Design: Built to handle increased loads and integrate with distributed systems.
Storage and Metadata: Manages video files in local storage and metadata in MongoDB.

Project Architecture

Components

Frontend (React): Provides a user-friendly interface for video uploads, management, and playback.
Backend (Node.js with Express): Handles API requests, video processing workflows, and communication with Kafka.
Kafka: Manages message queues for efficient batch processing.
Transcoding Service (FFmpeg): Handles video transcoding, segmentation, and thumbnail creation.
MongoDB: Stores metadata like video information, quality levels, and thumbnails.
File Storage: Stores processed video files and thumbnails locally.

Tech Stack

Node.js: Backend logic and API endpoints.
React: Frontend for user interaction.
Kafka: Manages distributed message queues for scalability.
FFmpeg: Performs video transcoding, segmentation, and thumbnail generation.
MongoDB: Stores metadata and provides quick access to processed data.
Docker: Ensures easy setup and consistent environments.
TailwindCSS: Enhances the frontend with modern styling.

Installation and Setup

Prerequisites

Install Docker.
Install Node.js (v16 or higher).
Clone the repository:

   git clone https://github.com/Ravikisha/RelaxTube.git
   cd RelaxTube

Steps

Run Docker Compose

   docker-compose up -d

Install Dependencies

   cd frontend && npm install
   cd ../backend && npm install
   cd ../transcoding-service && npm install

Start Services
- Backend:
```
 cd backend
 npm run dev
```

Frontend:
```
 cd frontend
 npm run dev
```
Transcoding Service:
```
 cd transcoding-service
 npm run dev
```

Access the Application Open your browser and navigate to http://localhost:3000.

Usage

Upload Videos: Users can upload videos through the frontend interface.
Processing: The backend processes the videos by:
- Transcoding them to multiple quality levels.
- Segmenting videos for HLS playback.
- Generating thumbnails.
Streaming: Processed videos are available for streaming via the frontend.
Batch Processing: Upload multiple videos for concurrent processing.

Screenshots

Homepage

Video Playback

Quality Selection

Upload Interface

Batch Upload

Scalability Features

Batch Processing: Process multiple videos simultaneously using Kafka.
Distributed Workers: Scale horizontally by adding workers for transcoding tasks.
Load Balancing: Distribute incoming requests across multiple backend servers.
Cloud Storage: Potential integration with AWS S3 or Google Cloud Storage for large-scale storage.
Monitoring: Use tools like Prometheus or Grafana for real-time monitoring and performance tracking.

Future Enhancements

Cloud deployment for global access and scalability.
Advanced analytics for tracking user interactions and video performance.
User authentication and access control.
Caching mechanisms for faster access to frequently requested content.

Contributing

We welcome contributions to RelaxTube! Feel free to submit pull requests, report issues, or suggest new features.

License

RelaxTube is licensed under the MIT License. See the LICENSE file for details.

Start exploring RelaxTube by visiting the GitHub Repository!

Building Scalable Web Applications with Microfrontends: A Detailed Walkthrough of Microfrontend Blog

Ravi Kishan — Sun, 29 Dec 2024 14:23:36 +0000

Introduction

In the rapidly evolving world of web development, creating scalable, maintainable, and modular applications is more important than ever. Enter microfrontend architecture—a game-changing approach that divides a monolithic frontend into smaller, independently deployable pieces.

This blog introduces Microfrontend Blog, a real-world implementation of microfrontends built using cutting-edge technologies like React, TailwindCSS, Clerk, Module Federation, and Firebase Firestore. Whether you're an experienced developer or just getting started with microfrontends, this project is a comprehensive guide to building modular web applications.

GitHub Repository: Microfrontend Blog

Project Overview

Microfrontend Blog is a blogging platform designed to demonstrate the power of microfrontend architecture. It splits the application into five key modules:

Auth Microfrontend: Handles user authentication using Clerk.
Dashboard Microfrontend: Allows users to create, edit, and manage blogs.
Viewer Microfrontend: Displays blogs with comment functionality.
Shared Components: A library of reusable components like headers, footers, and blog cards.
Container: Orchestrates the integration of all microfrontends.

By adopting Module Federation, each microfrontend is developed and deployed independently, enabling seamless collaboration across teams and simplifying the scaling process.

Features

Authentication: Secure login and signup with Clerk.
Blog Management: A rich dashboard for managing blogs.
Blog Viewing: Interactive blog display with a comments section.
Responsive UI: Styled with TailwindCSS for consistency across devices.
Scalability: Independent deployment of microfrontends.

Technologies Used

React: The foundation for building the UI.
TailwindCSS: A utility-first CSS framework for modern designs.
Clerk: A robust authentication library.
Firebase Firestore: Cloud-based database for blog storage.
Module Federation: Simplifies microfrontend integration.
Webpack: Efficient module bundler for development and production.

Architecture Diagram

The architecture demonstrates the interaction between microfrontends, the container, and backend services:

Getting Started

1. Prerequisites

Install Node.js (v16+).
Clone the repository:

  git clone https://github.com/Ravikisha/Microfrontend-Blog.git
  cd Microfrontend-Blog

2. Install Dependencies
For each microfrontend and shared components, run:

cd <microfrontend-folder>
npm install

3. Start the Development Server

npm start

4. Access the Application
Visit http://localhost:3005 to view the application.

Screenshots

Home Page:

Login Page:

Create Blog:

View Blog:

MicroFrontend Screenshots

Auth Microfrontend:

Dashboard Microfrontend:

Viewer Microfrontend:

Shared Components:

Container:

Key Benefits of Microfrontend Architecture

Independent Development: Teams can work on different microfrontends without stepping on each other's toes.
Scalability: Easily scale individual modules based on demand.
Reusability: Shared components streamline development and ensure design consistency.

Conclusion

The Microfrontend Blog project serves as a practical example of how microfrontend architecture can simplify development and improve scalability. With technologies like React, TailwindCSS, and Module Federation, developers can create robust and maintainable applications that meet modern web development demands.

Explore the code and start building your modular applications today!

GitHub Repository: Microfrontend Blog

Would you like me to add more details, such as common troubleshooting tips or deeper dives into individual microfrontends?

Introducing Stylesnap: Optimize Your CSS Like Never Before

Ravi Kishan — Sun, 29 Dec 2024 14:04:56 +0000

In the ever-evolving world of web development, efficiency and optimization are paramount. Meet Stylesnap, a cutting-edge solution for CSS optimization that simplifies your workflow and boosts performance. Designed for developers, this handy tool minimizes your CSS files by analyzing your project’s content and retaining only the styles you truly need.

What is Stylesnap?

Stylesnap is an NPX package tailored for modern web development. It scans your codebase—HTML, JSX, or any supported files—and generates a lightweight, optimized CSS file that eliminates unused styles. Whether you're using popular frameworks like Bootstrap, TailwindCSS, or custom CSS, Stylesnap has you covered.

Key Features

Selective CSS Extraction: Extracts only the required class names, tags, and selectors.
Framework Compatibility: Works seamlessly with CSS frameworks or custom styles.
Minification: Automatically minifies the generated CSS for improved performance.
Custom Configurations: Offers a customizable workflow using stylesnap.config.json.
Command-Line Simplicity: Easy-to-use CLI for quick integration.

Why Choose Stylesnap?

Enhanced Performance: Smaller CSS files mean faster page loads and better user experience.
Maintainability: Eliminates unused CSS, making your stylesheets cleaner and easier to manage.
Flexibility: Compatible with various frameworks and custom setups.
Developer-Friendly: Simple installation, intuitive CLI options, and detailed documentation.

Getting Started

Installation

Use npm to install Stylesnap as a development dependency:

npm install stylesnap --save-dev

Or run it directly with NPX:

npx stylesnap

Usage

Stylesnap’s CLI makes it easy to optimize your CSS. Here’s a quick example:

Initialize Configuration:

   npx stylesnap --init

This creates a stylesnap.config.json file in your project.

Update Configuration: Edit the file to suit your project’s needs:

   {
     "content": ["./src/**/*.html", "./src/**/*.jsx"],
     "css": "./src/styles.css",
     "output": "./dist/optimized.css",
     "minify": true
   }

Run Stylesnap:

   npx stylesnap

Your optimized CSS will be saved at the specified output location.

Real-World Benefits

By using Stylesnap, you’ll see immediate improvements in your development and deployment process:

Faster Load Times: Reduced CSS file size enhances website speed.
Smaller Builds: Ideal for production environments.
Streamlined Debugging: With unused CSS eliminated, debugging becomes simpler.

Contribute

Stylesnap is open-source, and contributions are welcome! If you encounter any issues or have ideas for improvement, feel free to open an issue or submit a pull request.

Start optimizing your CSS today with Stylesnap! 🚀 Streamline your workflow, boost performance, and take your web development projects to the next level.

A Comprehensive Guide to Building a Single Sign-On (SSO) Gateway with Node.js

Ravi Kishan — Sun, 22 Dec 2024 17:13:18 +0000

Single Sign-On (SSO) systems have become critical in today's interconnected application ecosystems. By allowing users to log in once and access multiple applications seamlessly, SSO simplifies authentication, enhances user experience, and bolsters security. This blog dives into the implementation of an SSO Gateway using Node.js, Express, and MongoDB, guiding you through its features, architecture, setup, and best practices.

What is a Single Sign-On Gateway?

An SSO Gateway is a centralized authentication system where users authenticate once and gain access to multiple interconnected applications without needing to reauthenticate. The Node-SSO-Gateway project demonstrates a robust yet simple implementation of such a system.

Key Features of the Node-SSO-Gateway

Centralized Authentication
- Users log in via a single SSO server, eliminating the need for multiple logins.
Token-Based Authorization
- Secure, stateless communication between the SSO server and consumer applications via JSON Web Tokens (JWT).
Cross-Domain Session Management
- Maintain seamless user sessions across multiple applications and domains.
MongoDB Integration
- Secure storage of user credentials with robust password hashing (e.g., bcrypt).
Dynamic Consumer App Registration
- Consumer applications can dynamically register themselves with the SSO server for authentication.
Logout Functionality
- Supports global and local session termination for enhanced security.

System Architecture

The system is divided into three primary components:

SSO Server

The central hub that authenticates users, manages sessions, and issues JWT tokens.
Consumer Applications (Clients)

Applications relying on the SSO server for authentication. Each client establishes a local session after verifying the token.
MongoDB

A database backend to securely store user data, including email and hashed passwords.

Architecture Diagram

How Does It Work?

User Login
- Users log in through the SSO server. Upon successful authentication, the server issues a JWT token and redirects the user to the desired consumer app.
Token Validation
- Consumer apps verify the JWT token with the SSO server before granting access to protected resources.
Session Management
- Both global (SSO server) and local (consumer app) sessions are managed, ensuring secure and consistent access.
Logout
- Users can log out from the SSO server, terminating the global session, or from a consumer app, terminating the local session.

Setting Up the Node-SSO-Gateway

1. Prerequisites

Node.js and npm installed.
MongoDB instance running (local or cloud-based).
Basic knowledge of JWT, Express, and MongoDB.

2. Clone the Repository

git clone https://github.com/Ravikisha/Node-SSO-Gateway.git
cd Node-SSO-Gateway

3. Install Dependencies

Navigate to the root directory of each component and install the required packages.

For the SSO Server

cd server
npm install

For Consumer Applications

cd client1
npm install

# In another terminal
cd client2
npm install

4. Configure MongoDB

Create a .env file in both the SSO Server and consumer apps with the following content:

MONGODB_URI=mongodb://localhost:27017/sso-db

5. Start the Applications

Start the SSO Server:

cd server
npm run dev

Start the consumer apps:

cd client1
npm run dev

# In another terminal
cd client2
npm run dev

6. Test the System

Visit http://localhost:3000 to access the SSO server login page.
Successfully log in to be redirected to consumer apps (http://localhost:3001 and http://localhost:3002).

Adding New Consumer Applications

Create a new app following the structure of client1.
Register the app’s domain in the SSO Server’s allowedOrigin configuration.

   const allowedOrigin = {
       "http://localhost:3001": true,
       "http://localhost:3002": true,
       "http://localhost:3003": true,
   };

Redirect authentication requests to the SSO Server.

Security Best Practices

HTTPS Everywhere
- Use HTTPS in production to ensure encrypted communication.
Secure JWT Storage
- Store JWT securely, preferably in HTTP-only cookies, to prevent XSS attacks.
Validate Origins
- Validate consumer app origins to prevent unauthorized requests.
Password Hashing
- Use strong hashing algorithms like bcrypt for storing user passwords.

Logout Functionality

Local Logout
- Removes the session from the consumer app only.
Global Logout
- Terminates the session on the SSO Server, logging the user out from all consumer apps.

Screenshots

Login Page

SSO Server Page

Consumer Application (Client1)

Consumer Application (Client2)

Conclusion

The Node-SSO-Gateway project offers a secure and scalable solution for centralized authentication across multiple applications. By leveraging modern web technologies like Node.js, Express, and JWT, the system ensures a seamless user experience and robust security. Whether you're building a microservices-based architecture or integrating multiple platforms, this SSO solution is a solid foundation for managing authentication effectively.

Explore the repository here and get started with centralized authentication today!

Building a Feature-Rich Load Balancer in TypeScript: A Detailed Overview

Ravi Kishan — Sun, 22 Dec 2024 16:45:02 +0000

Load balancers are essential components of modern distributed systems, ensuring scalability, fault tolerance, and optimal resource utilization. In this blog, we’ll explore the development and capabilities of a custom Load Balancer Implementation in TypeScript—a project that combines advanced load-balancing algorithms, health checks, self-healing mechanisms, and webhook notifications. This implementation mirrors the functionality of industry-standard tools like NGINX and HAProxy.

GitHub Repository

You can explore the complete project on GitHub: Load Balancer Implementation.

Key Features

Easy Configuration:

Configure all aspects of the load balancer through a config.json file. This includes backend server details, health check intervals, and load-balancing algorithms.
Load Balancing Algorithms:
- Random: Requests are sent to a randomly selected backend server.
- Round-Robin: Requests are distributed sequentially among backend servers.
- Weighted Round-Robin: Backend servers are prioritized based on assigned weights.
Health Checks:

Periodic pings to backend servers ensure only healthy servers receive traffic.
Self-Healing:

Automatically attempts to recover downed servers, with a configurable success rate.
Retries and Redirects:

Failed requests are retried on alternative healthy servers.
Webhook Alerts:

Notify administrators of server failures via custom webhook triggers. Alerts include:
- Individual server failures.
- Total backend server failure.
Scalability:

The modular design allows for easy addition or removal of backend servers.

Project Structure

The repository contains the following components:

Backend Server Simulation: Simulates multiple backend servers for load balancing.
Load Balancer Core: Manages traffic, health checks, retries, and notifications.
Configuration File: Allows users to define the behavior of the load balancer.

Getting Started

Prerequisites

Install Node.js and npm.
Clone the repository:

   git clone https://github.com/Ravikisha/Load-Balancer-Implementation.git
   cd Load-Balancer-Implementation
   npm install

Running the Application

Start Backend Servers: Run multiple backend servers on different ports using the command:

   npm run dev:be 8081
   npm run dev:be 8082
   npm run dev:be 8083

Launch the Load Balancer: Start the load balancer on the specified port:

   npm run dev:lb 8000

Send Requests: Use a tool like Postman or Curl to send HTTP requests to the load balancer at http://localhost:8000.

Testing and Monitoring

Simulate Backend Server Failures:
- Kill a backend server process.
- Observe automatic request redirection to other healthy servers.
Webhook Alerts:
- Configure a webhook URL in config.json for real-time alerts.
- Use services like Typed Webhook to test notifications.
Self-Healing:
- Check the logs for attempts to restart failed servers.

Configuration Options

The config.json file governs the behavior of the load balancer. Key parameters include:

{
  "lbPORT": 8000,
  "_lbAlgo": "rr",
  "be_servers": [
    { "domain": "http://localhost:8081", "weight": 1 },
    { "domain": "http://localhost:8082", "weight": 1 },
    { "domain": "http://localhost:8083", "weight": 1 }
  ],
  "be_retries": 3,
  "health_check_interval": 30000,
  "send_alert_webhook": "https://webhook.site/your-webhook",
  "enableSelfHealing": true
}

_lbAlgo: Choose between rand, rr, or wrr.
be_servers: Define backend servers and their weights.
send_alert_webhook: Specify a webhook URL for notifications.
enableSelfHealing: Enable or disable server recovery attempts.

Insights and Learning Outcomes

Developing this load balancer provided insights into:

Traffic Distribution Techniques: Understanding how different algorithms impact performance and fairness.
Fault Tolerance: Designing systems that gracefully handle failures and recover automatically.
Alerting Mechanisms: Using webhooks to keep administrators informed in real-time.
Configuration Management: Simplifying user experience through JSON-based settings.

Challenges and Future Scope

Challenges:

Ensuring low latency during health checks and retries.
Managing detached processes spawned during self-healing.

Future Enhancements:

Enhanced Health Checks: Add support for more complex health-check mechanisms.
SSL/TLS Support: Enable secure communication between clients and backend servers.
Dynamic Scaling: Integrate with cloud APIs to dynamically scale backend server pools.

Conclusion

This project demonstrates how a TypeScript-based load balancer can achieve features similar to enterprise-grade solutions like NGINX or AWS ELB. With robust fault tolerance, advanced load-balancing algorithms, and real-time alerting, this implementation serves as a practical example for developers looking to understand the inner workings of load balancers.

Explore the project on GitHub, try it out, and contribute to its future enhancements!

Introducing GitaVerse: Access Bhagavad Gita Verses Programmatically 🚀

Ravi Kishan — Tue, 17 Dec 2024 15:55:10 +0000

In the world of modern development, spiritual and literary texts can be made more accessible to developers through clean APIs and libraries. GitaVerse is a modern TypeScript library that enables you to access, explore, and retrieve shlokas (verses) from the Bhagavad Gita with ease.

🌟 What is GitaVerse?

GitaVerse is a TypeScript-based NPM library that allows developers to programmatically fetch the Bhagavad Gita's verses (shlokas), including translations, synonyms, and original Devanagari text.

The Bhagavad Gita is a profound Hindu scripture consisting of 700 verses across 18 chapters. With GitaVerse, you can:

Retrieve individual verses based on Chapter and Verse number.
Fetch all shlokas in a specific chapter.
Access translations, synonyms, and meanings in a structured format.
Build spiritual apps, educational tools, or study tools effortlessly.

🚀 Features of GitaVerse

✅ Fetch Any Shloka: Get verses from any chapter with full details.
✅ Detailed Information: Includes Devanagari text, verse translations, synonyms, and multiple meanings.
✅ Organized Data: All data is structured and typed with TypeScript interfaces for ease of use.
✅ Easy-to-Use API: Clean class-based methods for developers.
✅ Lightweight: Minimal dependencies for faster integration.
✅ TypeScript Support: Full type safety for robust development.

📥 Installation

You can install GitaVerse using npm or yarn:

npm install gitaverse

yarn add gitaverse

🔧 How to Use GitaVerse

Here’s a quick guide on how you can use the GitaVerse library.

1. Import GitaVerse and Initialize

Start by importing the GitaLibrary class and initializing it:

import { GitaLibrary } from "gitaverse";

const gita = new GitaLibrary();

2. Fetch Metadata About the Bhagavad Gita

Get an overview of the Bhagavad Gita, such as the total chapters and verses:

const metadata = gita.getDescription();
console.log(metadata);

/*
Output:
{
  title: "Bhagavad Gita",
  description: "The Bhagavad Gita, often referred to as the Gita, is a 700-verse Hindu scripture that is part of the Indian epic Mahabharata.",
  totalChapters: 18,
  totalVerses: 700
}
*/

3. Fetch All Shlokas in a Chapter

To retrieve all the verses from a specific chapter, use getChapter():

const chapter1Shlokas = gita.getChapter(1);

chapter1Shlokas.forEach((shloka) => {
  console.log(shloka.getSummary());
});

4. Fetch a Specific Shloka

Fetch a specific shloka using chapter number and verse number:

const shloka = gita.getShloka(1, 1);

console.log(shloka.getSummary());

/*
Output:
{
  chapter: "1",
  verse: "1",
  devanagari: "धृतराष्ट्र उवाच...",
  verseText: "Dhritarashtra said...",
  synonyms: "Dhritarashtra - King Dhritarashtra...",
  translation: "King Dhritarashtra inquired...",
  meaning: ["Literal meaning of the verse...", "Spiritual significance..."]
}
*/

5. Fetch All Shlokas Grouped by Chapters

If you want to get all verses organized by chapters, use getAllVerses():

const allVerses = gita.getAllVerses();

allVerses.forEach((chapter) => {
  console.log(
    `Chapter ${chapter.getShlokas().length} Shlokas available`
  );
});

📚 API Methods Overview

Here’s a quick overview of the available methods:

`GitaLibrary` Methods:

Method	Description
`getDescription()`	Get metadata about the Gita.
`getChapter(chapter)`	Fetch all shlokas in a specific chapter.
`getShloka(chapter, verse)`	Retrieve a specific shloka by chapter & verse.
`getAllVerses()`	Fetch all shlokas grouped by chapters.

`GitaShloka` Methods:

Method	Description
`getSummary()`	Retrieve a summary of the shloka details.
`getDevanagari()`	Get the Devanagari text of the verse.
`getTranslation()`	Get the verse translation.
`getMeaning()`	Get multiple meanings of the verse.

🛠 Use Cases

Here are a few ideas for integrating GitaVerse into your projects:

Spiritual Apps: Build apps to display Gita shlokas with translations and explanations.
Study Tools: Develop tools for students to explore and understand the Bhagavad Gita.
APIs: Serve Gita data through REST APIs for web or mobile apps.
Personal Projects: Use it for personal study and exploration of the Gita.

🌐 Links

NPM Package: gitaverse on npm
GitHub Repository: GitaVerse on GitHub

🤝 Contributing

We welcome contributions! If you'd like to add features or fix issues:

Fork the repository from GitHub.
Create a feature branch.
Submit a pull request.

For any suggestions or bugs, feel free to raise an issue.

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.

✨ Final Thoughts

With GitaVerse, exploring the timeless wisdom of the Bhagavad Gita becomes simple and developer-friendly. Whether you're building spiritual apps, study tools, or personal projects, GitaVerse provides everything you need to programmatically access and share the Gita's teachings.

"You have the right to work, but never to the fruit of work."

— Bhagavad Gita (Chapter 2, Verse 47)

Start Exploring the Gita Today with GitaVerse! 🌟

Install Now

Introducing NexaPHP: A Lightweight MVC PHP Framework

Ravi Kishan — Thu, 07 Nov 2024 16:54:24 +0000

Building PHP applications often involves a lot of boilerplate code and organization to maintain a clean structure. Many developers reach for frameworks like Laravel or Symfony to handle this, but what if you just need a light, straightforward MVC (Model-View-Controller) framework? NexaPHP might be exactly what you're looking for. This minimalist framework is designed for developers who want a lean structure without all the weight of larger frameworks, making it an ideal choice for learning or creating small to medium-sized applications.

Why NexaPHP?

NexaPHP is tailored for developers who value simplicity and want more control over the core framework functionality. The design of NexaPHP is straightforward and lets you focus on essential aspects of your application without navigating through heavy framework abstractions. Here’s what NexaPHP offers:

Lightweight and minimal - Core MVC components without excessive dependencies.
Easy setup and configuration - Straightforward configuration for database and routing.
Middleware support - Add custom middleware for enhanced request filtering.
Event-driven - Use custom events to customize application behavior.

Whether you're a beginner or an experienced developer wanting to learn MVC principles, NexaPHP’s small footprint allows you to dive directly into PHP web development.

Getting Started with NexaPHP

1. Installation

Install NexaPHP via Composer, which makes it easy to integrate into any PHP project:

composer require ravikisha/nexaphp

2. Basic Setup

To initialize a NexaPHP application, configure your application root directory and database details:

use ravikisha\nexaphp\Application;

$config = [
    'userClass' => \app\models\User::class,
    'db' => [
        'dsn' => 'mysql:host=localhost;dbname=testdb',
        'user' => 'root',
        'password' => 'password'
    ]
];

$app = new Application(__DIR__, $config);

This setup includes:

userClass: Defines the User model, critical for handling user authentication and management.
db: Provides database connection parameters, including Data Source Name (DSN), user, and password.

Key Components in NexaPHP

NexaPHP provides several foundational classes that power its core MVC structure:

Application: Manages the lifecycle of your app and orchestrates different components.
Router: Maps URLs to specific controllers and actions.
Request and Response: Handle HTTP requests and responses.
Database: Manages database connections and queries.
Session: Offers session management functions.
View: Handles the rendering of HTML templates.

Building Your First Controller

Controllers define how NexaPHP handles requests for different routes. Here’s an example of a SiteController:

namespace app\controllers;

use ravikisha\nexaphp\Controller;

class SiteController extends Controller
{
    public function home()
    {
        return $this->render('home');
    }

    public function contact()
    {
        return $this->render('contact');
    }
}

Using $this->render() renders a view file, while setLayout() can define custom layouts.

Defining Routes

The Router allows you to define GET and POST routes that correspond to specific controller actions:

$app->router->get('/', [SiteController::class, 'home']);
$app->router->post('/contact', [SiteController::class, 'contact']);

NexaPHP supports dynamic routes with parameters, allowing you to handle user-specific pages:

$app->router->get('/profile/{id}', [UserController::class, 'profile']);

Database Integration

NexaPHP uses PDO for database interactions, making it easy to integrate with various databases. Here’s a quick overview:

Defining a Model: Use models to interact with database tables.

namespace app\models;

use ravikisha\nexaphp\db\DBModel;

class User extends DBModel
{
    public string $id;
    public string $name;

    public static function tableName(): string
    {
        return 'users';
    }

    public function attributes(): array
    {
        return ['id', 'name'];
    }
}

Migrations: NexaPHP can run migrations to keep the database schema updated:
```
$app->db->applyMigrations();
```
CRUD Operations: NexaPHP provides methods like save() and findOne() for database operations.

Middleware Support

NexaPHP’s middleware feature allows you to implement request filtering and control. Here’s an example of creating and applying custom middleware:

namespace app\middlewares;

use ravikisha\nexaphp\middlewares\BaseMiddleware;

class AuthMiddleware extends BaseMiddleware
{
    public function execute()
    {
        // Authentication logic
    }
}

To register middleware:

$this->registerMiddleware(new AuthMiddleware(['profile', 'settings']));

Views and Templating

NexaPHP views offer a simple way to manage HTML templates. By default, templates are stored in the views folder, and you can use layout files to maintain a consistent design.

return $this->render('profile', ['name' => 'John Doe']);

Layouts can be defined under views/layouts, and placeholders like {{content}} allow views to be inserted dynamically.

Forms and Fields

NexaPHP offers a convenient form and field builder, making it easy to create dynamic HTML forms:

use ravikisha\nexaphp\form\Form;

$form = Form::begin('/submit', 'post');
echo $form->field($model, 'username');
Form::end();

You can render various field types such as password, email, and date fields for different form requirements.

Session Management

The Session class provides session handling, allowing you to set, get, and manage flash messages:

Application::$app->session->setFlash('success', 'Logged in successfully');

This is particularly useful for displaying temporary notifications.

Exception Handling

NexaPHP has built-in support for handling exceptions, including:

NotFoundException for invalid routes.
ForbiddenException for access control.

User Authentication

User authentication is managed through the abstract UserModel class, which provides foundational methods like login(), logout(), and isGuest().

class User extends UserModel
{
    public static function primaryKey(): string
    {
        return 'id';
    }

    public function getDisplayName(): string
    {
        return $this->username;
    }
}

Sample NexaPHP Application

Below is an example of a basic NexaPHP application setup:

require_once __DIR__ . '/vendor/autoload.php';

use ravikisha\nexaphp\Application;
use app\controllers\SiteController;

$config = [
    'userClass' => \app\models\User::class,
    'db' => [
        'dsn' => 'mysql:host=localhost;dbname=testdb',
        'user' => 'root',
        'password' => 'password'
    ]
];

$app = new Application(__DIR__, $config);

$app->router->get('/', [SiteController::class, 'home']);
$app->router->get('/contact', [SiteController::class, 'contact']);

$app->run();

Conclusion

NexaPHP provides a clean and concise way to build MVC applications with PHP. While it’s intended for learning and small projects, it’s a great choice for those who want to understand how an MVC framework works under the hood. Explore the framework on GitHub or install it via Composer to get started.

GitHub: NexaPHP GitHub

Composer: NexaPHP on Packagist

Building a Regex Engine in Go: Introducing MatchGo

Ravi Kishan — Mon, 04 Nov 2024 18:09:27 +0000

In today's programming landscape, regular expressions (regex) are invaluable tools for text processing, enabling developers to search, match, and manipulate strings with precision. I recently embarked on an exciting project to create a regex engine in Go, named MatchGo, utilizing a Non-deterministic Finite Automaton (NFA) approach. This blog post will walk you through the development journey of MatchGo, highlighting its features and practical usage.

Project Overview

MatchGo is an experimental regex engine designed for simplicity and ease of use. It allows you to compile regex patterns, check strings for matches, and extract matched groups. While it's still in development, I aimed to create a functional library that adheres to core regex principles, inspired by various resources and regex implementations.

Key Features

Basic Syntax Support: MatchGo supports foundational regex constructs, including:
- Anchors: ^ (beginning) and $ (end) of strings.
- Wildcards: . to match any single character.
- Character Classes: Bracket notation [ ] and negation [^ ].
- Quantifiers: *, +, ?, and {m,n} for specifying repetition.
- Capturing Groups: ( ) for grouping and backreferences.
Special Character Handling: MatchGo supports escape sequences and manages special characters in regex, ensuring accurate parsing and matching.
Multiline Support: The engine has been tested with multiline inputs, where . does not match newlines (\n), and $ correctly matches the end of lines.
Error Handling: Improved error handling mechanisms to provide clear feedback during compilation and matching.

Installation

To incorporate MatchGo into your Go project, simply run the following command:

go get github.com/Ravikisha/matchgo

Usage

Getting started with MatchGo is straightforward. Here’s how you can compile a regex pattern and test it against a string:

import "github.com/Ravikisha/matchgo"

pattern, err := matchgo.Compile("your-regex-pattern")
if err != nil {
    // handle error
}

result := pattern.Test("your-string")
if result.Matches {
    // Access matched groups by name
    groupMatchString := result.Groups["group-name"]
}

To find all matches in a string, use FindMatches:

matches := pattern.FindMatches("your-string")
for _, match := range matches {
    // Process each match
    if match.Matches {
        fmt.Println("Match found:", match.Groups)
    }
}

Example Code

Here’s a practical example demonstrating how to use MatchGo:

package main

import (
    "fmt"
    "github.com/Ravikisha/matchgo"
)

func main() {
    pattern, err := matchgo.Compile("([a-z]+) ([0-9]+)")
    if err != nil {
        fmt.Println("Error compiling pattern:", err)
        return
    }

    result := pattern.Test("hello 123")
    if result.Matches {
        fmt.Println("Match found:", result.Groups)
    }
}

This code will output:

Match found: map[0:hello 123 1:hello 2:123]

Development Insights

Developing MatchGo involved significant research and implementation of various regex principles. Here are some of the critical aspects of the engine:

NFA Implementation: The engine builds a non-deterministic finite automaton (NFA) from the regex patterns, enabling efficient matching.
Token Parsing: MatchGo parses the regex string into tokens, allowing for flexible matching strategies.
State Management: The engine maintains states for capturing groups and backreferences, enhancing its ability to handle complex regex patterns.
Extensibility: Although currently minimalistic, the engine is designed with extensibility in mind, allowing for future enhancements and additional features.

Resources and References

Throughout the development of MatchGo, I referred to various resources, including:

These resources provided invaluable insights and helped refine the implementation.

Conclusion

MatchGo is an exciting step into the world of regex engines, offering a simple yet functional tool for developers looking to integrate regex capabilities into their Go applications. As this project evolves, I look forward to enhancing its features and refining its performance.

Feel free to check out the GitHub repository for more information, contribute, or experiment with the engine in your own projects. Happy coding!

Building a URL Shortener with Rate Limiting and Redis in Go

Ravi Kishan — Mon, 04 Nov 2024 14:33:20 +0000

URL shorteners like Bitly or TinyURL are incredibly popular tools, but have you ever wondered what goes into building one? In this blog, we’ll dive into how I built a custom URL shortener in Go with rate limiting and a Redis database for data storage and IP tracking. We’ll cover the core features, the tech stack, and the challenges I encountered along the way.

Project Overview

This URL shortener application accepts long URLs from users, generates shorter, unique links, and allows users to customize the shortened alias if desired. The server redirects any visitor who uses the shortened URL to the original long URL.

Here's a quick overview of the primary components:

WebServer: Handles routing and requests using the Fiber framework.
Rate Limiter: Manages user requests to prevent abuse, limiting the number of requests an IP can make in a given timeframe.
URL Validator: Ensures URLs are in a valid format and ready for storage.
URL Generator: Generates unique short links for each long URL or uses custom aliases provided by users.
Redis Database: Stores URL mappings and IP rate limits.

With these features in mind, let’s break down the implementation.

Tech Stack

Go: Fast and efficient, Go is ideal for building a high-performance URL shortener.
Fiber: A web framework in Go, chosen for its lightweight performance and simplicity.
Redis: An in-memory database used to store URL mappings and IP quotas, giving us speed and persistence.
Docker: Containers make setting up Redis easy and ensure the application is portable and scalable.

Project Structure

The core files and folders are organized as follows:

.
├── main.go               # Entry point for the application
├── routes/
│   ├── shorten.go        # Handles URL shortening and redirects
├── database/
│   ├── redis.go          # Database connection logic
├── helpers/
│   ├── helper.go         # Utility functions for URL validation
├── .env                  # Environment variables
├── docker-compose.yml    # Docker setup for Redis

Setting Up the Application

1. Main Server Logic (`main.go`)

Our main application file sets up the routes for shortening and resolving URLs. Here’s the code snippet:

package main

import (
    "log"
    "os"

    "github.com/gofiber/fiber/v2"
    "github.com/gofiber/fiber/v2/middleware/logger"
    "github.com/joho/godotenv"

    "github.com/ravikisha/url-shortener/routes"
)

func setupRoutes(app *fiber.App) {
    app.Get("/:url", routes.ResolveURL)
    app.Post("/api/v1", routes.ShortenURL)
}

func main() {
    err := godotenv.Load()
    if err != nil {
        log.Fatal("Error loading .env file")
    }

    app := fiber.New()
    app.Use(logger.New())

    setupRoutes(app)

    log.Fatal(app.Listen(os.Getenv("APP_PORT")))
}

2. Rate Limiting and URL Shortening (`shorten.go`)

To prevent abuse, we use Redis to keep track of each IP address and limit the number of allowed requests. Here’s the flow:

Check Rate Limits: When a request is made, the rate limiter checks Redis to see how many requests the IP has made.
Process URL: If the rate limit is not exceeded, the server validates the URL and shortens it.
Generate or Use Alias: If the user provides a custom alias, we store it. Otherwise, we generate a unique ID.

package routes

import (
    "os"
    "strconv"
    "time"

    "github.com/asaskevich/govalidator"
    "github.com/go-redis/redis/v8"
    "github.com/gofiber/fiber/v2"

    "github.com/ravikisha/url-shortener/database"
    "github.com/ravikisha/url-shortener/helpers"
)

// Define structs for the request and response data
type request struct {
    URL         string        `json:"url"`
    CustomShort string        `json:"short"`
    Expiry      time.Duration `json:"expiry"`
}

type response struct {
    URL             string        `json:"url"`
    CustomShort     string        `json:"short"`
    Expiry          time.Duration `json:"expiry"`
    XRateRemaining  int           `json:"x-rate-remaining"`
    XRateLimitReset time.Duration `json:"x-rate-limit-reset"`
}

3. Redis Database Setup (`redis.go`)

In redis.go, we define a helper function to connect to Redis. This connection is used across different components to store short URLs and enforce rate limits. Here's a simple example of how Redis is configured:

package database

import (
    "context"
    "github.com/go-redis/redis/v8"
)

var Ctx = context.Background()

func NewClient(dbNum int) *redis.Client {
    rdb := redis.NewClient(&redis.Options{
        Addr:     "localhost:6379",
        Password: "",
        DB:       dbNum,
    })
    return rdb
}

Docker Setup

To simplify setting up Redis, I used Docker. This makes the application portable and easy to deploy.

version: '3'
services:
  redis:
    image: "redis:alpine"
    ports:
      - "6379:6379"

Running the Application

Clone the repository from GitHub: URLShortener
Run the Docker container for Redis:
```
docker-compose up -d
```

Set environment variables in .env:

DB_ADDR="localhost:6379"
DB_PASSWORD=""
APP_PORT=":6767"
DOMAIN="localhost:6767"
APP_QUOTA=10

Run the Go application:
```
go run main.go
```

Now, the application is live, and you can start shortening URLs!

Testing the URL Shortener

Shortening a URL

Send a POST request to /api/v1 with the following JSON payload:

{
    "url": "https://example.com",
    "short": "exmpl",
    "expiry": 24
}

Accessing a Shortened URL

Use the generated short URL, like http://localhost:6767/exmpl, to be redirected to https://example.com.

Key Learnings

Using Redis for Rate Limiting: Redis is incredibly fast, and using it for both URL storage and rate limiting was efficient and effective.
Building a REST API with Fiber: Fiber's simplicity and performance are well-suited for building APIs in Go.
Error Handling and Validation: Ensuring robust error handling and URL validation was essential to providing a user-friendly experience.

Future Improvements

There are a few features and optimizations I’d like to add in the future:

Admin Dashboard: A UI to track URL usage and monitor statistics.
Detailed Analytics: Track click counts, referrers, and user demographics.
Scalability: Deploy the app on a cloud provider and use distributed Redis for handling more extensive data.

Conclusion

Building this URL shortener was a rewarding experience and a great way to explore Go, Fiber, and Redis. This project provides a solid foundation, whether you're learning about backend development or exploring Go’s potential in web services.

If you'd like to see the code in action, check out the GitHub repository here. Let me know your thoughts or if you have suggestions for improving the project!

DEV Community: Ravi Kishan

How RelaxCSS Works: Building a TailwindCSS-Like Utility Engine

Overview and Introduction

Architecture Overview

Theme and Configuration System

Utility Parser and Generator

Plugin System

JIT Compilation and File Scanning

Preflight and CSS Output

Example Output and Live Usage

Conclusion

Ravikisha / RelaxCSS

RelaxCSS

PostCSS Plugin Usage

Building a Container Runtime from Scratch with Go (MyDocker)

Introduction

Namespaces

Control Groups (cgroups)

Project Architecture

Command-Line Interface and Main.go

Container Lifecycle (startContainer, child)

Networking

Image Handling and OCI Unpacking

Volumes and Port Mappings

Diagrams

Getting Started and Resources

Ravikisha / MyDocker

MyDocker is a lightweight container runtime built from scratch in Go that demonstrates how containerization works under the hood — similar to Docker but in a simplified form.

🐳 MyDocker

🚀 Features

🎯 Architecture

📦 Installation

Introducing RelaxLang: A Beginner-Friendly Programming Language

Why RelaxLang?

Architecture

Key Features of RelaxLang

1. Dynamic Typing

2. First-Class Functions

3. Classes and Inheritance

4. Control Flow

How to Get Started

1. Prerequisites

2. Installation

3. Running RelaxLang

Example Usage

The Technical Journey

Resources and Contributions

Docker Image:

GitHub Repository:

Final Thoughts

Building RelaxTube: A Scalable Video Transcoding and Streaming Application

Introduction

Key Features

Project Architecture

Components

Tech Stack

Installation and Setup

Prerequisites

Steps

Usage

Screenshots

Homepage

Video Playback

Quality Selection

Upload Interface

Batch Upload

Scalability Features

Future Enhancements

Contributing

License

Building Scalable Web Applications with Microfrontends: A Detailed Walkthrough of Microfrontend Blog

Introduction

Project Overview

Features

Technologies Used

Architecture Diagram

Getting Started

Screenshots

Screenshots

MicroFrontend Screenshots

Container Lifecycle (`startContainer`, `child`)

`GitaLibrary` Methods:

`GitaShloka` Methods: