localsend 딥다이브
— 파일 하나를 보내며 배우는 네트워크 앱의 설계

1프로젝트 한줄 요약

LocalSend는 같은 로컬 네트워크의 기기끼리 파일과 메시지를 주고받는 무료 오픈소스 앱입니다. 일반적인 로컬 전송에는 인터넷 연결이나 중앙 파일 보관 서버가 필요하지 않습니다. Windows 노트북과 Android 휴대폰처럼 운영체제가 다른 기기를 연결하는 것이 대표적인 쓰임새입니다.

각 기기가 보내는 클라이언트이면서 받는 서버이기도 하므로, 파일은 상대 기기로 직접 이동합니다. 여기서 서버는 거대한 데이터센터가 아니라 앱 안에서 요청을 기다리는 작은 프로그램을 뜻합니다. 받는 기기에 별도 서버 제품을 설치하는 구조가 아닙니다.

사용자가 보는 네 단계, 코드가 처리하는 네 가지 책임

2왜 주목받는가

2-1. 작은 불편을 여러 운영체제에서 풀어냅니다

GitHub Trending Dart Weekly #11이라는 순위와 95,312개의 스타는 관심의 크기를 보여줍니다. 특정 게시물이나 업데이트가 이번 주 관심을 일으켰다는 인과관계까지 보여주는 수치는 아닙니다. 프로젝트의 매력은 파일 하나를 옮기려고 계정·클라우드 업로드·공유 링크를 준비하는 수고를 줄인다는 제품의 효용으로 해석할 수 있습니다.

README는 Windows, macOS, Linux, Android, iOS, Fire OS 배포 경로를 안내합니다. 소스에도 app/android/, app/ios/, app/macos/, app/windows/, app/linux/가 있습니다. “크로스플랫폼”은 소개 문구에 머물지 않고 권한·창·파일 선택을 처리하는 플랫폼 코드로 이어집니다.

이 표는 전달 방식의 차이를 비교한 것입니다. 경쟁 제품의 모든 기능이나 전송 성능을 평가한 순위가 아닙니다. LocalSend도 게스트 Wi-Fi의 기기 격리나 방화벽에 막히면 바로 연결되지 않을 수 있습니다.

2-2. Dart 프로젝트에서 Rust 시스템 설계까지 만납니다

이 저장소의 학습 가치는 예쁜 공유 화면과 실제 네트워크 실패 처리가 한 흐름으로 연결된다는 데 있습니다. Flutter만 읽어도 상태 관리와 반응형 UI를 배우고, 더 내려가면 Rust의 비동기 I/O, TLS, 스트림, 취소 안전성을 만납니다.

cli/Cargo.toml의 localsend-cli는 같은 Rust 코어를 사용합니다. 화면이 달라도 통신 규칙을 재사용한다는 사실이 구조로 드러납니다. 공용 라이브러리를 분리하는 이유를 “중복을 줄인다”보다 구체적으로 이해하기 좋은 예입니다.

2-3. 최근 커밋과 실제 활성 기능은 구분해야 합니다

최근 커밋 6e37efd의 제목은 fix(webrtc): less blocking implementation (#3625)입니다. 하지만 app/lib/provider/network/webrtc/signaling_provider.dart에는 const webRTCEnabled = false;가 있습니다. app/lib/config/init.dart의 postInit()도 이 값이 참일 때만 시그널링 연결을 시작합니다.

3기술 스택 전체 지도

3-1. 언어와 도구 버전: 허용 범위와 고정값

3-2. 프론트엔드: Flutter 화면과 앱 상태

위 값은 app/pubspec.yaml의 선언값입니다. Refena, Slang, dart_mappable, file_picker는 pubspec.lock에서도 같은 버전을 확인할 수 있습니다. 앱은 로컬 경로 의존성 localsend_isolates를 통해 네트워크 계층을 사용합니다.

3-3. 백엔드: 앱 내부의 Rust 통신 코어

근거는 packages/core/Cargo.toml과 루트 Cargo.lock입니다. 일반 파일 전송 서버는 Axum이 아니라 Hyper 기반입니다. packages/core/src/http/server/mod.rs의 handle_request_inner()에서 메서드와 경로를 직접 분기합니다.

3-4. 언어 사이의 다리, CLI, 별도 서버

packages/localsend_isolates/pubspec.yaml은 flutter_rust_bridge: ^2.12.0을 선언하고, Rust 플러그인 크레이트는 flutter_rust_bridge = "=2.12.0"으로 정확한 버전을 지정합니다. 양쪽 잠금 파일도 2.12.0입니다. 이 다리가 Dart의 요청과 Rust의 결과를 연결합니다.

server/src/main.rs의 기본 바인딩은 SERVER_IP=0.0.0.0, SERVER_PORT=3000입니다. 이 서버는 로컬 파일 전송 때마다 파일을 맡기는 중앙 저장소가 아닙니다. 기본 앱에서 꺼져 있는 WebRTC 경로와 관련된 별도 프로그램입니다.

3-5. 인프라·빌드: 제품의 일관성도 코드로 검사합니다

기술 스택을 읽을 때는 라이브러리 이름뿐 아니라 어느 실행 대상이 그 기술을 사용하는지까지 연결해야 합니다. Flutter 앱, 기기 내부 HTTP 서버, CLI, 외부 시그널링 서버를 모두 “백엔드”라는 한 칸에 넣으면 설계의 핵심이 사라집니다.

4아키텍처 심화 분석

4-1. 전체 구조: 화면 밖에서 움직이는 통신

그림의 화살표는 책임 사이의 호출·메시지 흐름입니다. 파일 바이트가 매번 Flutter 화면을 통과한다는 뜻이 아닙니다. 받는 쪽은 Dart가 저장 대상을 결정하고, Rust가 실제 파일 내용을 기록하는 경로를 제공합니다.

출발점은 app/lib/main.dart와 app/lib/config/init.dart입니다. 시작 코드만 읽어도 앱이 어떤 서비스에 기대는지 보입니다. 모바일 앱이 다시 활성화될 때 ensureRunning()을 호출하는 부분은 운영체제가 중지된 앱의 소켓을 회수하는 상황을 고려한 설계입니다.

4-2. 발견과 전송은 다른 통신입니다

packages/core/src/multicast/mod.rs의 기본값은 IPv4 그룹 224.0.0.167, 포트 53317입니다. MulticastHandle::announce()가 기기 정보를 알리면 이를 들은 기기는 HTTP register 요청으로 응답합니다. 파일을 UDP 멀티캐스트로 뿌리는 구조가 아닙니다.

packages/core/src/multicast/socket.rs의 bind_multicast_sockets()는 네트워크 인터페이스별로 소켓을 만듭니다. Wi-Fi·유선·가상 어댑터가 함께 있을 때 한 소켓의 송신 인터페이스에만 의존하지 않기 위해서입니다. 자기 알림은 지문을 비교해 걸러냅니다.

멀티캐스트가 통하지 않을 때는 다른 길도 있습니다. app/lib/provider/network/scan_facade.dart의 StartSmartScan은 알림과 즐겨찾기 확인을 시작하고, 알려진 주소 확인이 끝난 뒤 1초의 유예 시간을 둡니다. 스캔 시작 이후 새 기기나 기존 기기를 한 번도 확인하지 못하면 서브넷 스캔으로 확장합니다. 대상 인터페이스는 최대 3개, Rust 발견 계층의 기본 요청 제한 시간은 500ms, 스캔 동시성 상수는 50입니다.

프로토콜 버전 2.2와 API 경로의 v2는 모순이 아닙니다. 세부 버전과 경로 버전이 구분됩니다. 서버에는 호환용 GET /api/localsend/v1/info도 남아 있으므로, v2 구현이라는 설명을 “v1 문자열을 가진 경로가 전혀 없다”로 확대해서는 안 됩니다.

4-3. 설계 패턴 ①: 타입이 있는 메시지로 작업자 분리

Dart isolate는 다른 isolate와 같은 변경 가능한 객체를 자유롭게 공유하는 작업자가 아닙니다. 메시지를 보내 일을 요청하고 결과 스트림을 받습니다. 이 저장소는 그 연결에 요청·결과 타입을 붙여 잘못된 메시지를 줄입니다.

// packages/typed_isolates/lib/src/isolate_helper.dart의 핵심 형태
class IsolateConnector<R, S> {
  // R: 작업자로부터 받는 메시지, S: 작업자에게 보내는 메시지
  final Stream<R> receiveFromIsolate;
  final SendPort _sendToIsolate;
  final Isolate isolate;

  // 생성자는 생략
  void sendToIsolate(S message) {
    _sendToIsolate.send(message);
  }
}

실제 isolate 생성은 TypedIsolates.startIsolate<R, S, P>()가 담당합니다. packages/localsend_isolates/lib/src/isolate/parent/parent_isolate_provider.dart의 IsolateSetupAction에서 그 사용 예를 볼 수 있습니다. 긴 제네릭을 만났다면 먼저 “받는 타입, 보내는 타입, 초기값 타입” 순서로 풀어 읽으세요.

상태도 자동으로 공유되지 않습니다. actions_sync.dart는 새 SyncState를 자식에게 보냅니다. ServerService.startServer()가 서버 시작 작업을 보내기 전에 별칭·포트·프로토콜을 먼저 동기화하는 순서는 중요합니다. 순서를 바꾸면 작업자가 예전 설정으로 시작할 수 있습니다.

4-4. 설계 패턴 ②: 통신 코어와 승인 정책의 분리

Rust 코어는 Flutter 대화상자를 모릅니다. packages/core/src/http/server/v2.rs의 prepare_upload()는 PrepareUpload 이벤트와 decision_tx를 만들고 앱의 답을 기다립니다. 앱은 일반 승인 창을 띄우거나, 설정에 따라 자동 승인할 수 있습니다.

// prepare_upload()의 흐름을 줄인 설명용 코드
let (decision_tx, decision_rx) = oneshot::channel();
let event = ServerEventV2::PrepareUpload {
    session_id,
    ip,
    info,
    cert_fingerprint,
    files,
    decision_tx,
};
event_tx.send(event).await?;
// 실제 구현은 취소 신호와 함께 tokio::select!로 기다립니다.
let decision = decision_rx.await?;

oneshot은 한 번의 답을 위한 채널입니다. 브리지의 RsHttpServer는 Rust 쪽에 응답 채널을 보관하고 respond_prepare_upload()로 답하게 합니다. Dart의 수신 이벤트는 server_isolate.dart를 거쳐 ServerService와 ReceiveController.onPrepareUpload()로 이어집니다.

따라서 ReceiveController는 HTTP 라우트 핸들러가 아니라 통신 계층이 이미 해석한 이벤트를 처리하는 앱의 정책 담당자입니다. 자동 수신도 코어를 고쳐 구현하는 대신 승인 응답을 빨리 보내는 방식으로 구성할 수 있습니다.

코어를 CLI에서도 쓰기 쉬운 이유가 여기에 있습니다. “통신은 이렇게 진행한다”와 “언제 허락할지, 어디에 저장할지”를 나눴기 때문입니다. 다른 UI를 붙여도 프로토콜을 다시 작성할 필요가 줄어듭니다.

4-5. 설계 패턴 ③: 상태 머신과 자원 정리 가드

packages/core/src/http/server/mod.rs의 세션 슬롯은 Option<SessionStateV2>로 상태를 표현합니다. 비어 있거나, 승인 대기 Pending이거나, 진행 중 Active입니다. prepare_upload()는 슬롯이 차 있으면 HTTP 409로 새 세션을 거절합니다.

세션 하나 안에는 여러 파일이 있을 수 있습니다. “동시에 하나의 수신 세션”을 “항상 파일 하나씩만 처리”로 바꿔 읽으면 안 됩니다. 승인된 파일에는 각각 UUID 토큰이 발급되며, upload()는 세션 ID·송신자 주소·파일 ID·토큰·현재 상태를 검사합니다.

PendingSessionGuard와 UploadGuard는 비정상 종료를 처리합니다. 요청을 처리하던 Future가 중간에 사라져도 Drop에서 정리 작업을 시작해 대기 슬롯을 비우거나 파일 상태를 실패로 정리합니다. 정상 진행 때는 disarm() 또는 finish()로 중복 정리를 막습니다.

체크섬 불일치 때의 업로드 시도 상한은 MAX_UPLOAD_ATTEMPTS = 3입니다. 모든 네트워크 오류를 무조건 세 번 재시도한다는 정책은 아닙니다. 어떤 오류가 다시 Pending으로 돌아가는지 finalize_file()의 분기를 읽어야 합니다.

4-6. 설계 패턴 ④: 스트리밍과 이벤트별 역압 정책

packages/core/src/http/server/common/save.rs의 save_req_to_target()는 HTTP 본문을 청크 단위로 읽습니다. 저장 대상은 FileUploadTarget::Path, Android의 Fd, 앱이 직접 소비하는 Stream으로 나뉩니다. 전체 파일을 하나의 거대한 바이트 배열로 먼저 만드는 경로와는 다릅니다.

파일 바이트는 기다려서 전달하고, 반복 가능한 중간 알림은 버릴 수 있게 하는 차이가 앱의 응답성을 지킵니다. 청크 채널의 16은 개수 제한이므로 이를 바로 “메모리 최대 16MB” 같은 수치로 바꿀 수는 없습니다. 청크 크기와 다른 버퍼도 영향을 줍니다.

packages/core/tests/event_backpressure.rs에는 이벤트를 소비하지 않아도 등록 응답과 스캔이 멈추지 않아야 한다는 테스트가 있습니다. 비동기 코드에서 중요한 것은 async를 붙이는 것만이 아니라, 누구의 느림이 누구를 기다리게 만드는가를 정하는 일입니다.

4-7. 암호화: HTTPS와 상대 확인은 서로 다른 질문입니다

packages/core/src/http/client/server_cert_verifier.rs의 PinnedServerCertVerifier::verify_server_cert()는 상대 인증서의 SHA-256 지문을 기대값과 비교합니다. 이 검사는 요청을 보낸 뒤가 아니라 TLS 핸드셰이크에서 수행됩니다. 지문이 다르면 파일 내용이나 요청 메타데이터를 보내기 전에 연결을 실패시킬 수 있습니다.

서브넷 스캔처럼 상대 지문을 미리 모르는 발견 경로도 있습니다. packages/core/src/discovery/mod.rs의 unpinned_client()는 기대 지문 없이 인증서를 검사하고, HTTPS 연결에서 확인한 지문을 이후 전송에 사용합니다. 이를 최초 사용 시 신뢰, TOFU라는 관점에서 읽을 수 있습니다. 반면 HTTPS로 멀티캐스트 알림에 답할 때는 알림에 담긴 지문을 처음부터 고정합니다. 처음 만난 상대가 의도한 사람인지까지 암호화가 자동으로 증명하지는 않습니다.

기기 인증서의 수명도 살펴볼 만합니다. app/lib/provider/persistence_provider.dart는 보안 컨텍스트가 저장돼 있지 않을 때 generateSecurityContext()로 생성해 저장합니다. README의 “기기에서 인증서를 생성한다”는 설명을 매 전송마다 새 인증서를 만든다는 뜻으로 읽으면 안 됩니다. 저장된 기기 신원을 이후 연결에도 사용하는 설계입니다.

일반 HTTPS 수신 모드에서는 클라이언트 인증서도 요구합니다. 웹 공유 모드에서는 브라우저 접속을 위해 선택 사항으로 바뀝니다. CustomClientCertVerifier와 start_server_with_listener()의 mandatory_client_auth 분기가 이 차이를 보여줍니다.

ReceiveController.onPrepareUpload()는 event.certFingerprint ?? event.info.fingerprint를 사용합니다. 인증서에서 확인한 지문을 우선하고, 인증서 지문이 없으면 요청 본문의 자기 신고값을 사용합니다. HTTP 연결뿐 아니라 클라이언트 인증서 없이 접속하는 HTTPS 웹 업로드도 이 경우에 해당합니다. “상대가 JSON에 적은 지문”과 “연결에서 증명한 신원”을 구분하는 연습에 좋은 코드입니다.

5디렉토리 구조 해부

5-1. 처음부터 모든 폴더를 읽을 필요는 없습니다

화면이 궁금하면 app/lib/pages/, 상태가 궁금하면 app/lib/provider/, 실제 전송 규칙이 궁금하면 packages/core/src/http/로 내려가면 됩니다. 경계 사이가 궁금할 때만 localsend_isolates를 펼치면 읽기 부담이 줄어듭니다.

packages/core/src/http/dto_v2.rs와 앱의 화면 모델은 같은 목적의 파일이 아닙니다. DTO는 네트워크에서 주고받는 모양을 나타내고, 화면 상태는 진행률·표시 이름·사용자 선택처럼 UI가 필요한 정보를 함께 가집니다. 서로 다른 모델을 무조건 하나로 합치면 한쪽 변경이 다른 쪽까지 번지기 쉽습니다.

5-2. 줄 수는 생성 코드와 함께 읽어야 합니다

커밋 6e37efd의 Git 추적 파일을 대상으로 한 물리 줄 수이며 빈 줄과 주석·테스트를 포함합니다. 우측 열은 app/lib/gen/, *.g.dart, *.mapper.dart, *.freezed.dart, 이름에 frb_generated가 들어가는 파일, cargokit/ 아래 파일을 제외한 수치입니다. 모든 종류의 생성 코드를 완벽하게 식별한 “순수 수작업 코드” 통계는 아닙니다.

Rust 코어만 보면 packages/core/src/는 10,728줄, packages/core/tests/는 3,857줄입니다. 테스트 분량이 크다는 관찰은 가능하지만 줄 수만으로 보안성이나 테스트 커버리지를 판단할 수는 없습니다. 생성된 번역·브리지 코드가 Dart 전체 규모를 크게 늘린다는 점도 함께 기억하세요.

6학습 포인트 (기술별)

6-1. Flutter: 화면 크기와 상태 구독 범위

app/lib/widget/responsive_builder.dart의 SizingInformation은 화면 폭 700 미만을 모바일, 700 이상을 태블릿·데스크톱, 800 이상을 데스크톱으로 판단합니다. 기기 이름을 맞히려는 분류가 아니라 주어진 공간에 맞는 레이아웃을 선택하는 기준입니다.

// 실제 SizingInformation의 폭 기준
const SizingInformation(double width)
    : isMobile = width < 700,
      isTabletOrDesktop = width >= 700,
      isDesktop = width >= 800;

실습 아이디어: 폭 699, 700, 799, 800에서 세 값이 어떻게 달라지는지 표로 적어보세요. 700~799 구간에서는 태블릿·데스크톱용 공간이지만 isDesktop은 거짓입니다. 경계값을 보는 습관이 UI 조건문의 오류를 줄입니다.

LocalSendApp.build()는 settingsProvider.select()로 테마 관련 값만 구독합니다. 모든 설정 변경이 전체 테마 판단에 영향을 주지 않도록 관심 범위를 좁히는 예입니다. 연습: “전송 진행률이 바뀔 때 테마 위젯도 다시 만들 필요가 있을까?”라는 질문으로 구독 지점을 분류해 보세요.

6-2. Refena: 상태와 동작을 나눠 읽기

nearbyDevicesProvider는 ReduxProvider이고, RegisterDeviceAction.reduce()가 발견한 기기를 상태에 반영합니다. 기기는 별칭이 아니라 지문을 키로 등록됩니다. 같은 사람이 별칭을 바꾸거나 같은 기기에 여러 주소가 생기는 상황에서 무엇을 식별자로 삼을지 배우는 지점입니다.

실습 아이디어: 같은 지문·다른 별칭인 기기 두 개와, 같은 별칭·다른 지문인 기기 두 개가 차례로 들어오면 목록이 몇 개가 되는지 예상해 보세요. 별칭을 식별자로 삼았을 때와 비교하면 모델 설계의 의미가 선명해집니다.

6-3. Dart isolate와 FRB: 두 경계를 구분하기

isolate 경계는 Dart 실행 문맥 사이의 메시지 통신이고, FRB 경계는 Dart와 Rust 사이의 호출·값 변환입니다. 둘을 같은 “백그라운드 처리”라고 뭉뚱그리지 마세요. IsolateHttpServerStartAction부터 start_server()까지 따라가면 두 경계를 차례로 볼 수 있습니다.

packages/localsend_isolates/flutter_rust_bridge.yaml의 rust_input: crate::api, rust_root: rust/, dart_output: lib/rust는 어떤 Rust API에서 Dart 코드를 생성하는지 보여줍니다. 생성 파일을 처음부터 읽기보다 packages/localsend_isolates/rust/src/api/server.rs의 수동 API부터 보세요.

실습 아이디어: “서버 시작 요청”·“서버 시작 완료”·“파일 수신 진행률”이 각각 어느 방향으로 두 경계를 건너는지 화살표로 그려보세요. 실제 파일 바이트도 그 길을 반드시 지나야 하는지 별도로 표시하는 것이 핵심입니다.

6-4. Rust: 소유권을 실제 자원과 연결하기

FileUploadTarget::Fd는 Android 파일 디스크립터의 소유권을 받아 저장이 끝나면 닫는 경로입니다. File::from_raw_fd() 주위의 안전 조건은 “이 정수를 누가 닫을 책임이 있는가”라는 현실의 문제와 연결됩니다. Rust 소유권은 값의 복사 여부만 다루는 추상 규칙이 아닙니다.

RsHttpServer의 Mutex<Option<mpsc::Receiver<ServerEventV2>>>도 유용합니다. listen()은 take()로 수신기를 가져가므로 한 번만 듣도록 구성됩니다. 두 번째 호출은 오류를 전달합니다. 타입과 작은 상태 변화로 사용 규칙을 표현하는 사례입니다.

실습 아이디어: “두 명이 같은 수신기를 소비하면 누가 어떤 이벤트를 받을까?”를 생각한 뒤, 한 번만 꺼내 쓰는 설계가 어떤 모호함을 없애는지 설명해 보세요. Mutex가 있다고 모든 기능을 여러 번 호출해도 된다는 뜻은 아닙니다.

6-5. 네트워크: 빠른 길을 먼저, 비싼 길은 나중에

단계적 발견은 알고리즘의 정답보다 시스템 비용을 생각하게 합니다. 알림 한 번과 알고 있는 주소 확인은 적은 작업으로 끝날 수 있지만, 서브넷 스캔은 여러 주소에 접속합니다. StartSmartScan의 유예 시간과 SCAN_CONCURRENCY는 사용자 대기 시간·트래픽·동시 연결 수를 조절하는 손잡이입니다.

실습 아이디어: 멀티캐스트 허용, 멀티캐스트 차단, 상대가 꺼짐이라는 세 환경에서 어떤 단계가 실행되고 언제 결과가 나올지 순서도를 만드세요. 500ms 제한 시간과 동시성 50만으로 모든 실제 소요 시간을 정확히 계산할 수 없는 이유도 적어보세요.

6-6. 저장 경로: 정상 파일 이름도 외부 입력입니다

packages/localsend_isolates/lib/src/task/server/file_saver.dart의 digestFilePathAndPrepareDirectory()는 디렉터리를 포함한 파일 이름을 다룹니다. 경로 이탈 시도와 절대 경로를 거부하는 처리, 기존 파일과 겹치면 이름에 번호를 붙이는 처리를 찾아볼 수 있습니다.

Rust의 packages/core/src/util/filename.rs는 Windows·HFS·FAT·POSIX 규칙을 나누고 MAX_LEN = 255바이트 제한을 둡니다. 글자 수와 UTF-8 바이트 수는 다르므로 한글 파일 이름을 다룰 때 특히 좋은 학습 소재입니다.

실습 아이디어: ../outside.txt, sub/photo.jpg, CON.txt, 긴 한글 파일 이름을 “경로 자체 거부”와 “이름 정리”로 나눠 예상하세요. file_saver_traversal_test.dart는 실제 경로 이탈 입력을, Rust 파일의 테스트는 이름 규칙을 읽는 출발점입니다.

6-7. 다국어: 번역도 제품의 데이터 계약

한국어 번역은 app/assets/i18n/ko.json, 누락 번역 목록은 _missing_translations_ko.json입니다. 생성된 app/lib/gen/strings_ko.g.dart를 직접 수정하면 다음 생성 작업에서 변경이 사라질 수 있습니다.

app/test/unit/i18n_test.dart는 번역 접근 코드의 컴파일과 Flutter의 언어 지원을 확인합니다. 실습 아이디어: 수신 승인 문구 하나를 골라 JSON 키 → 생성 접근자 → 화면 사용처를 연결해 보세요. 번역이 표시되는 위치까지 이해하면 문구 길이와 버튼 폭도 함께 고려하게 됩니다.

좋은 학습은 기술 이름을 수집하는 대신, 한 데이터가 경계를 지날 때 책임과 형태가 어떻게 바뀌는지 설명하는 데서 시작됩니다.

7하드웨어 / 시스템 요구사항

7-1. 일반 사용자에게 필요한 환경

README는 iOS에서 다른 앱의 공유 기능으로 보내려면 14 이상이 필요하다고 덧붙입니다. 지원 표는 배포 앱의 안내이고, 빌드 파일의 개별 타깃 값은 그 일부입니다. 타깃 하나의 낮은 숫자만 보고 앱 전체의 최소 OS 버전을 바꾸어 설명하면 안 됩니다.

인터넷이 필요 없다는 말은 네트워크가 필요 없다는 뜻이 아니며, 같은 Wi-Fi에서도 기기 간 통신이 허용돼야 합니다. 상대가 안 보일 때는 UI 오류부터 의심하기보다 발견 단계와 실제 접속 단계를 나눠 살펴보세요.

7-2. 개발 환경에서 구분할 버전

compileSdk와 targetSdk는 빌드 설정의 선언값입니다. 이 값만으로 빌드 성공이나 실제 지원 OS 범위를 보증할 수는 없습니다. 정량 RAM·디스크 요구량과 플랫폼별 모든 도구 버전이 한곳에 고정돼 있지는 않습니다. SDK·의존성 캐시·Rust 빌드 산출물은 앱 설치 크기와 별도로 공간을 차지합니다.

8직접 해볼 수 있는 실습 과제

첫 두 과제는 소스를 읽고 표·그림을 만드는 것만으로 할 수 있습니다. 나머지는 독립된 연습 코드나 테스트 실험 환경에서 확장할 과제입니다. 기능을 바꾸기 전에 현재 계약을 설명할 수 있는지 확인하세요.

# 저장소 루트에서 실행하는 읽기용 검색 예시
rg -n 'class StartSmartScan|onPrepareUpload' app/lib
rg -n 'async fn (register|prepare_upload|upload)' packages/core/src/http/server/v2.rs
rg -n 'save_req_to_target|UPLOAD_CHANNEL_CAPACITY' packages/core/src/http/server/common/save.rs

// 과제용 Dart 순수 함수. 실제 서버 API를 호출하는 코드는 아닙니다.
Set<String> selectSmallFiles(Map<String, int> sizes) {
  const limit = 1024 * 1024;
  return {
    for (final entry in sizes.entries)
      if (entry.value >= 0 && entry.value <= limit) entry.key,
  };
}

실습의 완료 기준은 기능을 흉내 내는 데서 끝나지 않고, 실패한 뒤에도 다음 작업이 가능한지 설명하는 것입니다.

9관련 기술 심화 학습 로드맵

Dart·Flutter를 처음 접한다면 Rust 코어부터 정독할 필요는 없습니다. 먼저 화면에서 보이는 상태를 이해하고, HTTP의 요청·응답을 익힌 다음 언어 경계를 내려가세요. 아래 일정은 학습 순서의 예시이며 주당 학습량에 따라 늘려도 됩니다.

이 표의 짧은 파일 이름은 앞 절에서 소개한 경로의 파일을 가리킵니다. 같은 이름의 v2.rs는 특히 HTTP 클라이언트·서버 양쪽에 있으므로, 상태 머신을 읽을 때는 packages/core/src/http/server/v2.rs를 선택하세요.

주차가 바뀔 때 스스로 묻는 질문

1. 1 → 2주: 이 화면의 데이터는 누가 갖고 있고, 무엇이 바뀌면 다시 그려질까요?
2. 2 → 3주: 목록에 보이는 기기는 단순 알림만 들은 상대인가요, 실제 접속으로 확인한 상대인가요?
3. 3 → 4주: 사용자 결정을 기다리는 동안 어떤 실행 문맥이 어떤 메시지를 기다릴까요?
4. 4 → 5주: 기다리던 요청이 사라지면 누가 슬롯·파일 상태·자원을 정리할까요?
5. 5 → 6주: 앱이 바빠졌을 때 통신까지 멈추지 않으려면 무엇을 버리고 무엇을 기다려야 할까요?

그다음에 선택할 두 갈래

다음 기술로 넘어갈 기준은 문법을 다 외웠는지가 아니라, 지금 읽은 계층의 입력·출력·실패 책임을 설명할 수 있는지입니다.

10핵심 키워드 사전

11참고 링크

공식 저장소와 프로젝트 문서

• localsend/localsend 공식 저장소 — 프로젝트 소개와 배포 경로
• LocalSend 공식 홈페이지 — 사용자를 위한 다운로드·안내의 출발점
• 이 커밋의 README — 기능·지원 OS·문제 해결 안내
• LocalSend Protocol 공식 저장소 — 외부 구현과 통신할 때 참고할 규약
• v1.18.2 릴리스 — 배포판 설명과 파일 확인
• 기여·배포 문서 — 변경 제안과 릴리스 절차의 안내
• Apache-2.0 라이선스 원문 — 사용·수정·배포 조건 확인

본문의 핵심 소스로 바로 가기

• 앱 초기화: preInit / postInit — 의존성을 준비하고 통신을 시작하는 순서
• isolate 생성과 연결 상태 — 현재 구현의 자식 작업자 세 개
• Rust 발견 계층 — 알림·접속 확인·단계적 스캔
• 전송 준비·업로드·취소 구현 — 승인 채널, 토큰, 정리 가드
• Rust → Dart 서버 API — 이벤트 스트림과 응답 채널 보관
• 스트리밍 파일 저장 — 저장 대상·쓰기 버퍼·체크섬
• 상대 인증서 지문 검증 — 데이터를 보내기 전의 확인
• 이벤트 포화 테스트 — 정보성 이벤트 때문에 통신이 멈추지 않아야 한다는 계약
• 파일 경로 이탈 테스트 — 외부 입력을 저장 경로에 쓰기 전의 검증
• WebRTC 활성화 조건 — 코드의 존재와 기본 동작 구분
• CI의 검사 목록 — 앱·Rust·패키징 버전을 함께 확인

관련 기술 공식 학습 자료

• Flutter 문서 · Dart 동시성 문서 — 위젯과 isolate 개념의 기반
• refena_flutter · Slang — 상태 관리와 번역 코드 생성
• flutter_rust_bridge 문서 — Dart와 Rust API 연결
• The Rust Programming Language — 소유권·enum·오류 처리
• Tokio 튜토리얼 — 비동기 작업과 채널
• Hyper · Reqwest · rustls — HTTP 서버·클라이언트·TLS 라이브러리
• Cargo 워크스페이스 · Pub 워크스페이스 — 여러 패키지를 관리하는 구조

현재 상태 (2026-10-23 확인)